https://wiki.flashrom.org/api.php?action=feedcontributions&user=Dhendrix&feedformat=atomflashrom - User contributions [en]2024-03-29T15:55:55ZUser contributionsMediaWiki 1.40.0https://wiki.flashrom.org/index.php?title=Flashrom/1.2&diff=2490Flashrom/1.22021-08-17T05:14:04Z<p>Dhendrix: </p>
<hr />
<div>{{DISPLAYTITLE:flashrom/1.2}}<br />
<br />
After about eight months, flashrom ''1.2'' is out. This release was rushed a bit so that we have a release that includes numerous build fixes that have been merged since v1.1. Fedora's build system started to encounter compilation issues that needed to be addressed for their upcoming release, so that became our canary in the coal mine this time around.<br />
<br />
==Other highlights==<br />
* Meson support (hello fwupd!)<br />
* Layout improvements/fixes and many, many code cleanups.<br />
* New chips: MX25U25635F, MX25L51245G, GD25Q256D, M95M02-A125, N25Q/MT25Q variants, W25Q128JW_DTR, AT25SF321, S25FL512S<br />
* New programmers: National Instruments USB-845x, Tin Can Tools Flyswatter/Flyswatter 2, STLINK V3, more Intel PCHs (Apollo Lake, Cannon Lake variants, Ice Lake U)<br />
* Reduced dependency on libusb0<br />
* Syntax: Added --flash-name and --flash-size arguments to print information about the flash chip<br />
<br />
= Download =<br />
<br />
flashrom ''1.2'' can be downloaded in various ways:<br />
<br />
Anonymous checkout from the git repository at https://review.coreboot.org/flashrom.git (tag ''v1.2'')<br />
<br />
A tarball is available for download at<br />
<br />
https://download.flashrom.org/releases/flashrom-v1.2.tar.bz2 [https://download.flashrom.org/releases/flashrom-v1.2.tar.bz2.asc (GPG signature)], fingerprint: <code>58A4 868B 25C7 CFD6 62FB 0132 A3EB 95B8 D978 0F68</code><br />
<br />
and more in the "Tags" section of CGit at<br />
<br />
https://review.coreboot.org/cgit/flashrom.git</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Flashrom/1.2&diff=2489Flashrom/1.22021-08-17T05:13:10Z<p>Dhendrix: /* Download */</p>
<hr />
<div>{{DISPLAYTITLE:flashrom/1.2}}<br />
<br />
After about eight months, flashrom ''1.2'' is out. This release was rushed a bit so that we have a release that includes numerous build fixes that have been merged since v1.1. Fedora's build system started to encounter compilation issues that needed to be addressed for their upcoming release, so that became our canary in the coal mine this time around.<br />
<br />
==Other highlights==<br />
* Meson support (hello fwupd!)<br />
* Layout improvements/fixes and many, many code cleanups.<br />
* New chips: MX25U25635F, MX25L51245G, GD25Q256D, M95M02-A125, N25Q/MT25Q variants, W25Q128JW_DTR, AT25SF321, S25FL512S<br />
* New programmers: National Instruments USB-845x, Tin Can Tools Flyswatter/Flyswatter 2, STLINK V3, more Intel PCHs (Apollo Lake, Cannon Lake variants, Ice Lake U)<br />
* Reduced dependency on libusb0<br />
* Syntax: Added --flash-name and --flash-size arguments to print information about the flash chip<br />
<br />
= Download =<br />
<br />
flashrom ''1.2'' can be downloaded in various ways:<br />
<br />
Anonymous checkout from the git repository at https://review.coreboot.org/flashrom.git (tag ''v1.2'')<br />
<br />
A tarball is available for download at<br />
<br />
https://download.flashrom.org/releases/flashrom-v1.2.tar.bz2 [https://download.flashrom.org/releases/flashrom-v1.2.tar.bz2.asc (GPG signature)]. Fingerprint: <code>58A4 868B 25C7 CFD6 62FB 0132 A3EB 95B8 D978 0F68</code><br />
<br />
and more in the "Tags" section of CGit at<br />
<br />
https://review.coreboot.org/cgit/flashrom.git</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2461Per region file arguments2021-05-11T16:27:52Z<p>Dhendrix: /* Alternative #2 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* File argument is mandatory; No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about positional or optional argument to -r/-w/-v and makes them consistent with -E.<br />
* Files (chip-sized and region-sized) are handled in a consistent manner similar to standard Unix commands such as ls, rm, cat, etc.<br />
* Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.<br />
* Need to ensure chip-sized file is used at most once<br />
* We can either deprecate `-i`, or treat it as a special case for operations on the whole chip (erase options or chip-sized file).<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2460Per region file arguments2021-05-11T16:23:50Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about positional or optional argument to -r/-w/-v and makes them consistent with -E.<br />
* Files (chip-sized and region-sized) are handled in a consistent manner similar to standard Unix commands such as ls, rm, cat, etc.<br />
* Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.<br />
* Need to ensure chip-sized file is used at most once<br />
* We can either deprecate `-i`, or treat it as a special case for operations on the whole chip (erase options or chip-sized file).<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2459Per region file arguments2021-05-11T06:33:27Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about optional argument to -r/-w/-v and makes them consistent with -E.<br />
* Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.<br />
* Need to ensure chip-sized file is used at most once<br />
* We can either deprecate `-i`, or treat it as a special case for operations on the whole chip (erase options or chip-sized file).<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2458Per region file arguments2021-05-11T06:32:45Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about optional argument to -r/-w/-v and makes them consistent with -E.<br />
* Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.<br />
* Need to ensure chip-sized file is used at most once<br />
* We can either deprecate `-i`, or treat it as a special case for operations in the whole chip (erase options or chip-sized file).<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2457Per region file arguments2021-05-10T05:53:13Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure file is used at most once<br />
* Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2456Per region file arguments2021-05-10T05:52:33Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure file is used at most once<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v.<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2455Per region file arguments2021-05-10T05:52:06Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* -r/-w/-v is set only once<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure only 0 or 1 chip-sized file is used<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v.<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2454Per region file arguments2021-05-10T05:50:01Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* Must err out if -r/-w/-v are mixed.<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure only one chip-sized file is used<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v and -i<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prog -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2453Per region file arguments2021-05-10T05:49:17Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* Must err out if -r/-w/-v are mixed.<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure only one chip-sized file is used<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v and -i<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|Alternative #3<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prof -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2452Per region file arguments2021-05-10T05:48:12Z<p>Dhendrix: /* Alternative #3 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* Must err out if -r/-w/-v are mixed.<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure only one chip-sized file is used<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v and -i<br />
* We can either deprecate `-i`, or treat it as a special case for chip-sized files and erase operations. The latter is less inconsistent but preserves some functionality.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|Alternative #3 (no optional args, treat <file> and <region>:<file> the same)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prof -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2451Per region file arguments2021-05-10T05:47:04Z<p>Dhendrix: </p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Alternative #3 ==<br />
<br />
-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.<br />
-r|-w|-v region:region.bin file.bin<br />
<br />
* Must err out if -r/-w/-v are mixed.<br />
* Eliminates concerns about optional argument to -r/-w/-v<br />
* Need to ensure only one chip-sized file is used<br />
* Chip-sized file and <region>:<filename> arguments are passed in consistently; no difference in treatment with regard to -r/-w/-v and -i<br />
* We can either deprecate `-i`, or treat it as a special modifier for chip-sized files. The latter is inconsistent but preserves some functionality.<br />
<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|Alternative #3 (no optional args, treat <file> and <region>:<file> the same)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog file.bin -r<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|flashrom -r -p prog -l layout -i region file.bin<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -r -p prog -l layout region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -r -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -w -p prog file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|flashrom -w -p prof -l layout -i region file.bin<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -w -p prog -l layout region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -w -p prog -l layout region:region.bin file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -v -p prog file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|flashrom -v -p prof -l layout -i region file.bin<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -v -p prog -l layout region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2450Per region file arguments2021-05-10T04:46:15Z<p>Dhendrix: /* Alternative #2 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2449Per region file arguments2021-05-10T04:45:49Z<p>Dhendrix: /* Alternative #2 */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Eliminates inconsistent usage of `-i` when working with region-sized files vs. chip-sized files.<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot manipulate regions and chip-sized files in a single operation.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2448Per region file arguments2021-05-09T22:12:10Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot utilize regions and chip-sized files easily.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|n/a<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|n/a<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|n/a<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E (?)<br />
|n/a<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2447Per region file arguments2021-05-09T21:54:46Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot utilize regions and chip-sized files easily.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2 (deprecate `-i`)<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|?<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|?<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|?<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|n/a<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2446Per region file arguments2021-05-09T21:52:51Z<p>Dhendrix: </p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== Alternative #1 ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Alternative #2 ==<br />
<br />
Deprecate `-i`, embed region into -r/-w/-v<br />
<br />
-r|-w|-v [<region>:]<filename><br />
<br />
* No optional or non-positional arguments<br />
* Must err out if -r/-w/-v are mixed.<br />
* Cannot utilize regions and chip-sized files easily.<br />
* Erasing specific regions will be unsupported since -E does not take arguments.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Alternative #1<br />
|Alternative #2<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -r<br />
|?<br />
|flashrom -p prog -l layout -r region:region.bin<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout -i region:region.bin -r file.bin<br />
|?<br />
|flashrom -p prog -l layout -r region:region.bin -r file.bin<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|flashrom -p prog -l layout -w region:region.bin<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|?<br />
|flashrom -p prog -l layout -w region:region.bin -w file.bin<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|n/a<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|flashrom -p prog -l layout -v region:region.bin<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|n/a<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2445Per region file arguments2021-05-09T00:09:19Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== More explicit alternative ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Proposed syntax<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout-i region:region.bin -r<br />
|?<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout-i region:region.bin -r file.bin<br />
|?<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|-<br />
|Write chip-sized file while applying region-specific patches [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|?<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2444Per region file arguments2021-05-08T23:59:41Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== More explicit alternative ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Proposed syntax<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout-i region:region.bin -r<br />
|?<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file [1]<br />
|flashrom -p prog -l layout-i region:region.bin -r file.bin<br />
|?<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|-<br />
|Write chip-sized file and apply patches over certain regions [2]<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|?<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
<br />
[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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2443Per region file arguments2021-05-08T23:57:26Z<p>Dhendrix: /* Use cases */</p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== More explicit alternative ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Proposed syntax<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout-i region:region.bin -r<br />
|?<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file*<br />
|flashrom -p prog -l layout-i region:region.bin -r file.bin<br />
|?<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|-<br />
|Write chip-sized file and apply patches over certain regions**<br />
|flashrom -p prog -l layout -i region:region.bin -w file.bin<br />
|?<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
* This is a niche case used in some ChromeOS scripts that might not be necessary anymore.<br />
** 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.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Per_region_file_arguments&diff=2442Per region file arguments2021-05-08T23:46:50Z<p>Dhendrix: </p>
<hr />
<div>== Current chromium impl. ==<br />
<br />
Current chromium flashrom implements the syntax like this:<br />
<br />
[-i <region>[:<file>]]... -r|-w|-v [<filename>]<br />
<br />
Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)<br />
<br />
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.<br />
<br />
==== Rules: ====<br />
* Argument to -r/-w/-v is optional.<br />
** If used, it tells flashrom to operate on a ROM-sized file.<br />
** If not, flashrom will only operate on region-sized files specified in -i arguments.<br />
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.<br />
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.<br />
<br />
* For reading:<br />
** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''.<br />
** 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<br />
<br />
* For writing and verifying:<br />
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.<br />
** 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.<br />
** Regions with files specified via '''-i region:<file>''' must not overlap<br />
<br />
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes<br />
<br />
== More explicit alternative ==<br />
<br />
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...<br />
<br />
Easier to implement, no optional arguments, no ''non-positional'' arguments.<br />
<br />
==== Rules for sanity: ====<br />
<br />
* combinations of '''-r/-w/-v''' are not allowed<br />
* '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') may only be specified once<br />
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either<br />
<br />
==== optionally, stricter ====<br />
<br />
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation:<br />
<br />
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)<br />
<br />
== Files not matching the region's size ==<br />
<br />
Both syntaxes can be extended for files that are smaller than the region:<br />
<br />
<region>[<filename><br />
<br />
would denote that the file's contents should be placed at the start/bottom<br />
of the region,<br />
<br />
<region>]<filename><br />
<br />
that the file's contents should be placed at the end/top of the region.<br />
By default the uncovered part of the region should be kept as is, unless<br />
<br />
--pad<br />
<br />
is specified, in which case the uncovered part would be padded with the<br />
flash chip's erased state (usually 0xff).<br />
<br />
==== Additonal rules ====<br />
<br />
* Beside `:`, `[` and `]` wouldn't be allowed in region names.<br />
<br />
== Use cases ==<br />
<br />
{| class="wikitable"<br />
|-<br />
|Operation<br />
|CrOS syntax<br />
|Proposed syntax<br />
|-<br />
|Read entire chip into file<br />
|flashrom -p prog -r file.bin<br />
|flashrom -p prog -r file.bin<br />
|-<br />
|Read region(s) into chip-sized file<br />
|flashrom -p prog -l layout -i region -r file.bin<br />
|?<br />
|-<br />
|Read region(s) into region-sized files<br />
|flashrom -p prog -l layout-i region:region.bin -r<br />
|?<br />
|-<br />
|Read region(s) into region-sized files and into chip-sized file*<br />
|flashrom -p prog -l layout-i region:region.bin -r file.bin<br />
|?<br />
|-<br />
|Write chip-sized file to chip<br />
|flashrom -p prog -w file.bin<br />
|flashrom -p prog -w file.bin<br />
|-<br />
|Write regions(s) from chip-sized file to chip<br />
|flashrom -p prog -l layout -i region -w file.bin<br />
|?<br />
|-<br />
|Write region(s) from region-sized files to chip<br />
|flashrom -p prog -l layout -i region:region.bin -w<br />
|?<br />
|-<br />
|Verify using a chip-sized file<br />
|flashrom -p prog -v file.bin<br />
|flashrom -p prog -v file.bin<br />
|-<br />
|Verify regions using a chip-sized file<br />
|flashrom -p prog -l layout -i region -v file.bin<br />
|?<br />
|-<br />
|Verify regions using region-sized files<br />
|flashrom -p prog -l layout -i region:region.bin -v<br />
|?<br />
|-<br />
|Erase chip<br />
|flashrom -p prog -E<br />
|flashrom -p prog -E<br />
|-<br />
|Erase regions(s)<br />
|flashrom -p prog -l layout -i region -E<br />
|flashrom -p prog -l layout -i region -E<br />
|}<br />
<br />
* This is a niche case used in some ChromeOS scripts that might not be necessary anymore.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=ME&diff=2436ME2020-10-18T19:51:49Z<p>Dhendrix: </p>
<hr />
<div>ME stands for Management Engine (or Manageability Engine) and refers to an [[EC|Embedded Controller]] found in Intel chipsets. It uses different versions of an [http://en.wikipedia.org/wiki/ARC_International ARC] 32-bit microcontroller that runs its own operating system independently from the user's. The ME has access to all kinds of buses which allows for out-of-band processing which is used for features like [http://en.wikipedia.org/wiki/Intel_Active_Management_Technology Active Management Technology], but it makes it also a very interesting target for black hats. The firmware it runs is secured by certificates stored in ROM, but it is a complex beast and it is very unlikely that there is no [http://invisiblethingslab.com/resources/misc09/Quest%20To%20The%20Core%20(public).pdf way around its security measures] (intentional backdoors included). For further details about the ME please see these excellent [http://2012.ruxconbreakpoint.com/assets/Uploads/bpx/Breakpoint%202012%20Skochinsky.pdf slides by Igor Skochinsky] ([[Media:ME - Breakpoint 2012 Skochinsky.pdf|mirror]]) and the [http://web.it.kth.se/~maguire/DEGREE-PROJECT-REPORTS/100402-Vassilios_Ververis-with-cover.pdf Security Evaluation of AMT by Vassilios Ververis].<br />
<br />
= Effects on flashrom =<br />
The firmware of the ME usually shares the flash memory with the firmware of the host PC (BIOS/UEFI/coreboot). The address space is separated into regions (similar to partitions on a harddisk). The first one (''Descriptor region'') contains configuration data which contains something similar to a partition table and access rights for the different devices that can access the flash (host CPU, ME, GbE controller). These restrictions are enforced by the chipset's SPI controller which is the main interface for flashrom to access the flash chip(s) attached to the chipset. Intel recommends to set the descriptor region read-only and to forbid reads and writes to the ME region by the host CPU. Writes by the host could interfere with the code running on the ME. This means that flashrom which runs on the host PC can not access the ME firmware region of the flash at all in this configuration. flashrom detects that, warns the user and disables write access for safety reasons in that case.<br />
<br />
== Unlocking the ME region ==<br />
There are a few ways to enable full access to the ME region, but they are not user friendly at all in general. Also, the Descriptor region is not affected by these actions, so it is still not possible to access the complete flash memory even when the ME region is unlocked.<br />
For the different possibilities please see [https://review.coreboot.org/cgit/flashrom.git/plain/Documentation/mysteries_intel.txt the documentation in our repository].<br />
<br />
= Suggested workarounds =<br />
* If you just want to update the proprietary firmware of the board use the vendor tool(s).<br />
* If you need full access to the flash chip get an [[Supported_programmers|external programmer]] and try [[ISP|in-circuit programming]].<br />
* If you only need to update the BIOS region, then you may use the options `--ifd -i bios --noverify-all` to write (and verify) only the BIOS region as described in the Intel flash descriptor.<br />
<br />
= See also =<br />
* The respective [http://www.coreboot.org/Intel_Management_Engine coreboot page on the management engine]<br />
* [https://review.coreboot.org/cgit/flashrom.git/plain/Documentation/mysteries_intel.txt The documentation in our repository]</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=MSI_JSPI1&diff=2435MSI JSPI12020-10-16T04:58:41Z<p>Dhendrix: </p>
<hr />
<div>JSPI1 is a 5x2 or 6x2 2.0mm pitch pin header on many MSI motherboards.<br />
It is used to recover from bad boot ROM images. Specifically, it appears to be used to connect an alternate ROM with a working image. Pull the #HOLD line low to deselect the onboard SPI ROM, allowing another SPI ROM to take its place on the bus. Pull the #WP line high to disable write-protection. Some boards use 1.8V flash chips, while others use 3.3V flash chips; Check the flash chip datasheet to determine the correct value.<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (5x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|VCC||1||2||VCC<br />
|-<br />
|MISO||3||4||MOSI<br />
|-<br />
|#SS||5||6||SCLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|#HOLD||9||''10''||''NC''<br />
|}<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (6x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|VCC||1||2||VCC<br />
|-<br />
|SO||3||4||SI<br />
|-<br />
|#SS||5||6||CLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|NC||9||10||NC (no pin)<br />
|-<br />
|#WP||11||12||#HOLD<br />
|}<br />
<br />
{| class="wikitable"<br />
!name!!function<br />
|-<br />
|VCC||Voltage (See flash chip datasheet)<br />
|-<br />
|MISO||SPI Master In/Slave Out<br />
|-<br />
|MOSI||SPI Master Out/Slave In<br />
|-<br />
|#SS||SPI Slave (Chip) Select (active low)<br />
|-<br />
|SCLK||SPI Clock<br />
|-<br />
|GND||ground/common<br />
|-<br />
|#HOLD||SPI hold (active low)<br />
|-<br />
|#WP||SPI write-protect (active low)<br />
|-<br />
|NC||Not Connected (or no pin)<br />
|}</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=MSI_JSPI1&diff=2434MSI JSPI12020-10-16T04:58:11Z<p>Dhendrix: </p>
<hr />
<div>JSPI1 is a 5x2 or 6x2 2.0mm pitch pin header on many MSI motherboards.<br />
It is used to recover from bad boot ROM images. Specifically, it appears to be used to connect an alternate ROM with a working image. Pull the #HOLD line low to deselect the onboard SPI ROM, allowing another SPI ROM to take its place on the bus. Pull the #WP line high to disable write-protection. Some boards use 1.8V flash chips, while others use 3.3V flash chips; Check the flash chip datasheet to determine the correct value.<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (5x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|VCC||1||2||VCC<br />
|-<br />
|MISO||3||4||MOSI<br />
|-<br />
|#SS||5||6||SCLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|#HOLD||9||''10''||''NC''<br />
|}<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (6x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|VCC||1||2||VCC<br />
|-<br />
|SO||3||4||SI<br />
|-<br />
|#SS||5||6||CLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|NC||9||10||NC (no pin)<br />
|-<br />
|#WP||11||12||#HOLD<br />
|}<br />
<br />
{| class="wikitable"<br />
!name!!function<br />
|-<br />
|VCC||Voltage (See up flash chip datasheet)<br />
|-<br />
|MISO||SPI Master In/Slave Out<br />
|-<br />
|MOSI||SPI Master Out/Slave In<br />
|-<br />
|#SS||SPI Slave (Chip) Select (active low)<br />
|-<br />
|SCLK||SPI Clock<br />
|-<br />
|GND||ground/common<br />
|-<br />
|#HOLD||SPI hold (active low)<br />
|-<br />
|#WP||SPI write-protect (active low)<br />
|-<br />
|NC||Not Connected (or no pin)<br />
|}</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=MSI_JSPI1&diff=2433MSI JSPI12020-10-16T04:57:01Z<p>Dhendrix: </p>
<hr />
<div>JSPI1 is a 5x2 or 6x2 2.0mm pitch pin header on many MSI motherboards.<br />
It is used to recover from bad boot ROM images. Specifically, it appears to be used to connect an alternate ROM with a working image. Pull the #HOLD line low to deselect the onboard SPI ROM, allowing another SPI ROM to take its place on the bus. Pull the #WP line high to disable write-protection. Some boards use 1.8V flash chips, while others use 3.3V flash chips; Check the flash chip datasheet to determine the correct value.<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (5x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|3VSB||1||2||3VSB<br />
|-<br />
|MISO||3||4||MOSI<br />
|-<br />
|#SS||5||6||SCLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|#HOLD||9||''10''||''NC''<br />
|}<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (6x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|VCC||1||2||VCC<br />
|-<br />
|SO||3||4||SI<br />
|-<br />
|#SS||5||6||CLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|NC||9||10||NC (no pin)<br />
|-<br />
|#WP||11||12||#HOLD<br />
|}<br />
<br />
{| class="wikitable"<br />
!name!!function<br />
|-<br />
|VCC||Voltage (See up flash chip datasheet)<br />
|-<br />
|MISO||SPI Master In/Slave Out<br />
|-<br />
|MOSI||SPI Master Out/Slave In<br />
|-<br />
|#SS||SPI Slave (Chip) Select (active low)<br />
|-<br />
|SCLK||SPI Clock<br />
|-<br />
|GND||ground/common<br />
|-<br />
|#HOLD||SPI hold (active low)<br />
|-<br />
|#WP||SPI write-protect (active low)<br />
|-<br />
|NC||Not Connected (or no pin)<br />
|}</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=MSI_JSPI1&diff=2432MSI JSPI12020-10-13T03:05:50Z<p>Dhendrix: </p>
<hr />
<div>JSPI1 is a 5x2 or 6x2 2.0mm pitch pin header on many MSI motherboards.<br />
It is used to recover from bad boot ROM images. Specifically, it appears to be used to connect an alternate ROM with a working image. Pull the #HOLD line low to deselect the onboard SPI ROM, allowing another SPI ROM to take its place on the bus. Pull the #WP line high to disable write-protection.<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (5x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|3VSB||1||2||3VSB<br />
|-<br />
|MISO||3||4||MOSI<br />
|-<br />
|#SS||5||6||SCLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|#HOLD||9||''10''||''NC''<br />
|}<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (6x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|#HOLD||1||2||#WP<br />
|-<br />
|NC||3||4||NC<br />
|-<br />
|NC||5||6||GND<br />
|-<br />
|CLK||7||8||#SS<br />
|-<br />
|SI||9||10||SO<br />
|-<br />
|NC||11||12||''3VSB''<br />
|}<br />
<br />
{| class="wikitable"<br />
!name!!function<br />
|-<br />
|3VSB||standby 3.3V<br />
|-<br />
|MISO||SPI Master In/Slave Out<br />
|-<br />
|MOSI||SPI Master Out/Slave In<br />
|-<br />
|#SS||SPI Slave (Chip) Select (active low)<br />
|-<br />
|SCLK||SPI Clock<br />
|-<br />
|GND||ground/common<br />
|-<br />
|#HOLD||SPI hold (active low)<br />
|-<br />
|#WP||SPI write-protect (active low)<br />
|-<br />
|NC||Not Connected (or no pin)<br />
|}</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=MSI_JSPI1&diff=2431MSI JSPI12020-10-13T01:40:57Z<p>Dhendrix: </p>
<hr />
<div>JSPI1 is a 5×2 or 6x2 2.0mm pitch pin header on many MSI motherboards.<br />
It is used to recover from bad boot ROM images. Specifically, it appears to be used to connect an alternate ROM with a working image. Pull the #HOLD line low to deselect the onboard SPI ROM, allowing another SPI ROM to take its place on the bus. Pull the #WP line high to disable write-protection.<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (5x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|3VSB||1||2||3VSB<br />
|-<br />
|MISO||3||4||MOSI<br />
|-<br />
|#SS||5||6||SCLK<br />
|-<br />
|GND||7||8||GND<br />
|-<br />
|#HOLD||9||''10''||''NC''<br />
|}<br />
<br />
{| class="wikitable"<br />
|+ JSPI1 (6x2)<br />
!name!!pin!!pin!!name<br />
|-<br />
|#HOLD||1||2||#WP<br />
|-<br />
|NC||3||4||NC<br />
|-<br />
|NC||5||6||GND<br />
|-<br />
|CLK||7||8||#SS<br />
|-<br />
|SI||9||10||SO<br />
|-<br />
|NC||11||12||''3VSB''<br />
|}<br />
<br />
{| class="wikitable"<br />
!name!!function<br />
|-<br />
|3VSB||standby 3.3V<br />
|-<br />
|MISO||SPI Master In/Slave Out<br />
|-<br />
|MOSI||SPI Master Out/Slave In<br />
|-<br />
|#SS||SPI Slave (Chip) Select (active low)<br />
|-<br />
|SCLK||SPI Clock<br />
|-<br />
|GND||ground/common<br />
|-<br />
|#HOLD||SPI hold (active low)<br />
|-<br />
|#WP||SPI write-protect (active low)<br />
|-<br />
|NC||Not Connected (or no pin)<br />
|}</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2429Development Guidelines2020-07-19T19:23:29Z<p>Dhendrix: /* Push your patch */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'')<br />
and will only add backported fixes to the release.<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]. When sending a patch via the mailing list, send it in-line instead of as an attachment so that reviewers can easily comment on specific parts of it.<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [https://www.flashrom.org/Development_Guidelines#Merging_to_branches Merging to branches]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
<br />
* If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom''<br />
<br />
* If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''.<br />
<br />
* If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
* If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Windows&diff=2428Windows2020-07-04T17:13:23Z<p>Dhendrix: /* Requirements */</p>
<hr />
<div>= Using flashrom on Windows =<br />
<br />
== Requirements ==<br />
In order to use flashrom on Windows you must either build it from source as explained below or just download a snapshot from [http://ra.openbios.org/~idwer/flashrom/mingw/ here].<br />
If your programmer is COM or LPT-based, there is nothing more to do, because Windows has all drivers needed.<br />
<br />
It isn't so easy for USB-based devices, because they needed a special libusb-win32 driver, that must be generated and installed to make it available to the flashrom executable.<br />
Because the nature of the generation process, the driver has no digital signature and can't be installed on 64-bit Windows versions without some preparations. <br />
<br />
== Obtaining libusb-win32 ==<br />
The required installation file can be found on [http://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/ the libusb-win32 project site].<br />
Please use the same version that was used for flashrom compilation as indicated by the download path.<br />
<br />
Download the file named ''libusb-win32-bin-x.y.z.t.zip'' and unpack ''/libusb-win32-bin-x.y.z.t/bin'' directory from it.<br />
<br />
== Making libusb-based driver for your device ==<br />
* Attach your USB device and click on ''Cancel'' or ''Close'' on the Driver Installation Wizard window. <br />
<br />
* Run inf-wizard.exe from the unpacked ''bin'' directory. Click on ''Next''. <br />
<br />
[[Image:Inf-Wizard-List.png]]<br />
<br />
* Select your device from the list, click on ''Next''.<br />
<br />
[[Image:Inf-Wizard-Settings.png]]<br />
<br />
* Do not alter Vendor ID, Product ID and MI. You can alter Manufacturer and Device names, if you want. Click on ''Next''.<br />
<br />
* Select the destination for the newly created driver and click on Save.<br />
<br />
[[Image:Inf-Wizard-Done.png]] <br />
<br />
* If you are using 32bit Windows version or 64bit Windows version with unsigned driver installation option enabled, click on ''Install Now...'' to install the driver.<br />
<br />
* If you receive an error message instead of a successful driver installation, disable the enforced driver signing (your favorite search engine will give you details about that) and install the driver after that.<br />
<br />
* Detach your device and attach it once again to finish the installation.<br />
<br />
== Using flashrom ==<br />
After installing the drivers successfully you can use flashrom without Administrator privileges.<br />
Consult the man page about how to use it in general and the options available for your programmer.<br />
<br />
= Building flashrom on Windows using MinGW/MSYS. =<br />
<br />
Before you set up a MinGW/MSYS build environment, note that you may find usable Windows binaries in our [http://buildbot.flashrom.org/buildresults/?M=D buildbot archive]. However, they are usually untested and not recommended to be trusted blindly.<br />
<br />
== Requirements ==<br />
<br />
=== MinGW/MSYS ===<br />
<br />
In order to build flashrom and various of its dependencies, we need a UNIX-like environment on Windows, which is provided by MinGW/MSYS.<br />
<br />
* Download the [http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get-inst/ latest version] (20110530 currently) of the automated [http://mingw.org/ MinGW] installer named '''mingw-get-inst''' (double-click the [http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get-inst/mingw-get-inst-20110530/mingw-get-inst-20110530.exe/download installer *.exe], which will download and install all components).<br />
** Make sure you enable "MinGW Compiler Suite", "C++ compiler", "MSYS Basic System", and "MinGW Developer Toolkit" in the installer.<br />
** For simplicity it's recommended to leave the default install location of '''c:\MinGW''' unchanged.<br />
<br />
Now open a MinGW shell via '''Start/Programs/MinGW/MinGW Shell''' and do the following:<br />
<br />
$ '''mingw-get update'''<br />
$ '''mingw-get install msys-wget msys-unzip'''<br />
<br />
* Additionally, '''pkg-config''' is needed. There are a few ways to do this. The MinGW FAQ has [http://www.mingw.org/wiki/FAQ some suggestions]: Extract the binary from GTK or use an alternative implementation. A flashrom user describes the steps for extracting pkg-config from GTK in [https://github.com/flashrom/flashrom/issues/149#issuecomment-653763669 this issue on Github].<br />
<br />
If you are using MSYS2, '''pacman''' can also be used:<br />
<br />
$ pacman -S mingw-w64-x86_64-pkg-config # 64-bit<br />
$ pacman -S mingw-w64-i686-pkg-config # 32-bit<br />
<br />
=== libusb-win32 ===<br />
<br />
* Download and execute [http://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/1.2.6.0/libusb-win32-devel-filter-1.2.6.0.exe/download libusb-win32-devel-filter-1.2.6.0.exe].<br />
* Download and extract [http://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/1.2.6.0/libusb-win32-bin-1.2.6.0.zip/download libusb-win32-bin-1.2.6.0.zip].<br />
** Copy '''lusb0_usb.h''' to (the equivalent of) '''/usr/local/include'''.<br />
<br />
=== libftdi ===<br />
<br />
* Install libftdi. The easiest method is probably to use the [http://picusb.googlecode.com/files/libftdi-0.18_mingw32.zip libftdi-0.18_mingw32.zip] binaries from [http://code.google.com/p/picusb/downloads/list here].<br />
** Extract the ZIP file into a temporary directory.<br />
** Copy '''dll/libftdi.dll''' to '''/usr/local/bin'''.<br />
** Copy '''lib/libftdi.a''' and '''lib/libftdi.dll.a''' to '''/usr/local/lib'''.<br />
** Copy '''include/ftdi.h''' to '''/usr/local/include'''.<br />
<br />
== Building flashrom ==<br />
<br />
Checkout the flashrom source code (see the [[Downloads#Installation_from_source|download page]] for instructions), then:<br />
<br />
$ '''cd flashrom'''<br />
$ '''make'''<br />
<br />
= Building (cross-compiling) flashrom on Linux for Windows using MinGW. =<br />
First you need to install MinGW (on Ubuntu it is enough to install the package mingw32).<br />
Of course all the normal build utilities are needed like make etc. (usually contained in a package named build-essential or similar).<br />
If you want to use libusb or libftdi you need to get the headers and static library files (*.a).<br />
The latter can either be downloaded pre-built or need to be (cross-)compiled.<br />
For libusb-win32 this even requires a Windows SDK which makes the whole point of cross-compiling a bit moot.<br />
See the respective source packages for documentation on how to cross-compile them.<br />
<br />
The headers and libraries should be organized in a Unix-like directory layout, i.e. a (sub) directory named '<tt>lib</tt>' containing the static libraries (<tt>*.a</tt>), '<tt>bin</tt>' with non-static libraries (<tt>*.dll</tt>) if need be, and '<tt>include</tt>' with the headers (<tt>*.h</tt>).<br />
<br />
You can then compile flashrom.exe with<br />
$ '''make CC=i686-w64-mingw32-gcc LIBS_BASE=/path_to_the_base_directory_containing_the_libraries_and_headers/'''<br />
A relative path (originating in the flashrom directory) is allowed as LIBS_BASE's value.<br />
The compiler to be used (given by the CC value) depends on the MinGW edition you are using.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2413Development Guidelines2020-03-31T16:32:19Z<p>Dhendrix: /* Using Github */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'')<br />
and will only add backported fixes to the release.<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]. When sending a patch via the mailing list, send it in-line instead of as an attachment so that reviewers can easily comment on specific parts of it.<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [https://www.flashrom.org/Development_Guidelines#Merging_to_branches Merging to branches]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
<br />
* If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
<br />
* If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''.<br />
<br />
* If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
* If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=ME&diff=2412ME2020-03-02T22:49:38Z<p>Dhendrix: /* Suggested workarounds */</p>
<hr />
<div>ME stands for Management Engine (or Manageability Engine) and refers to an [[EC|Embedded Controller]] found in Intel chipsets. It uses different versions of an [http://en.wikipedia.org/wiki/ARC_International ARC] 32-bit microcontroller that runs its own operating system independently from the user's. The ME has access to all kinds of buses which allows for out-of-band processing which is used for features like [http://en.wikipedia.org/wiki/Intel_Active_Management_Technology Active Management Technology], but it makes it also a very interesting target for black hats. The firmware it runs is secured by certificates stored in ROM, but it is a complex beast and it is very unlikely that there is no [http://invisiblethingslab.com/resources/misc09/Quest%20To%20The%20Core%20(public).pdf way around its security measures] (intentional backdoors included). For further details about the ME please see these excellent [http://2012.ruxconbreakpoint.com/assets/Uploads/bpx/Breakpoint%202012%20Skochinsky.pdf slides by Igor Skochinsky] ([[Media:ME - Breakpoint 2012 Skochinsky.pdf|mirror]]) and the [http://web.it.kth.se/~maguire/DEGREE-PROJECT-REPORTS/100402-Vassilios_Ververis-with-cover.pdf Security Evaluation of AMT by Vassilios Ververis].<br />
<br />
= Effects on flashrom =<br />
The firmware of the ME usually shares the flash memory with the firmware of the host PC (BIOS/UEFI/coreboot). The address space is separated into regions (similar to partitions on a harddisk). The first one (''Descriptor region'') contains configuration data which contains something similar to a partition table and access rights for the different devices that can access the flash (host CPU, ME, GbE controller). These restrictions are enforced by the chipset's SPI controller which is the main interface for flashrom to access the flash chip(s) attached to the chipset. Intel recommends to set the descriptor region read-only and to forbid reads and writes to the ME region by the host CPU. Writes by the host could interfere with the code running on the ME. This means that flashrom which runs on the host PC can not access the ME firmware region of the flash at all in this configuration. flashrom detects that, warns the user and disables write access for safety reasons in that case.<br />
<br />
== Unlocking the ME region ==<br />
There are a few ways to enable full access to the ME region, but they are not user friendly at all in general. Also, the Descriptor region is not affected by these actions, so it is still not possible to access the complete flash memory even when the ME region is unlocked.<br />
For the different possibilities please see [https://review.coreboot.org/cgit/flashrom.git/plain/Documentation/mysteries_intel.txt the documentation in our repository].<br />
<br />
= Suggested workarounds =<br />
* If you just want to update the proprietary firmware of the board use the vendor tool(s).<br />
* If you need full access to the flash chip get an [[Supported_programmers|external programmer]] and try [[ISP|in-circuit programming]].<br />
* If you only need to update the BIOS region, then you may use the options `--ifd -i bios --noverify-all` to write (and verify) only the BIOS region as described in the Intel flash descriptor.<br />
<br />
= See also =<br />
* The respective [http://www.coreboot.org/Intel_Management_Engine coreboot page on the management engine]</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Contact&diff=2411Contact2019-12-27T19:34:04Z<p>Dhendrix: </p>
<hr />
<div>[[Flashrom]] related mails are welcome on the flashrom mailing list at [mailto:flashrom@flashrom.org flashrom@flashrom.org]. '''Please do NOT send any BIOS images or F segment dumps to the list!'''<br />
<br />
E-mails with binary files attached will be rejected. Images for things such as scope or logic analyzer traces are acceptable if hosted on a third-party photo sharing service that assigns a unique URL to the image, such as Google Photos. This prevents the photo URL from being abused for malicious or inappropriate content.<br />
<br />
Please note that the list is moderated for non-subscribers and we recommend to [http://www.flashrom.org/mailman/listinfo/flashrom subscribe] first.<br />
<br />
== Subscription ==<br />
<br />
* https://mail.coreboot.org/postorius/lists/flashrom.flashrom.org/<br />
<br />
== Archives ==<br />
<br />
* https://mail.coreboot.org/hyperkitty/list/flashrom@flashrom.org/<br />
<br />
* http://www.flashrom.org/pipermail/flashrom/ (Up to Dec. 2018)<br />
<br />
* http://marc.info/?l=flashrom<br />
<br />
* http://www.mail-archive.com/flashrom@flashrom.org/<br />
<br />
* http://blog.gmane.org/gmane.linux.bios.flashrom<br />
<br />
== IRC ==<br />
<br />
You can also contact us via [[IRC]] if you prefer that.<br />
<br />
== Moderation rules ==<br />
<br />
If your mail is too big (the current limit is 256 kB) or if you're not on the subscriber list, your mail will be held for moderation. If your mail contains any BIOS images or F segment dumps (instead of links which are fine), the mail will be rejected for legal reasons (we do not have the right to distribute BIOS images).<br />
<br />
[[Mailinglist/Moderation howto|Moderation howto]] for moderators.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Contact&diff=2410Contact2019-12-22T18:49:31Z<p>Dhendrix: </p>
<hr />
<div>[[Flashrom]] related mails are welcome on the flashrom mailing list at [mailto:flashrom@flashrom.org flashrom@flashrom.org]. '''Please do NOT send any BIOS images or F segment dumps to the list!'''<br />
<br />
E-mails with binary files will be rejected. Images for things such as scope or logic analyzer traces are acceptable if hosted on a third-party photo sharing service that assigns a unique URL to the image, such as Google Photos. This prevents the photo URL from being abused for malicious or inappropriate content.<br />
<br />
Please note that the list is moderated for non-subscribers and we recommend to [http://www.flashrom.org/mailman/listinfo/flashrom subscribe] first.<br />
<br />
== Subscription ==<br />
<br />
* https://mail.coreboot.org/postorius/lists/flashrom.flashrom.org/<br />
<br />
== Archives ==<br />
<br />
* https://mail.coreboot.org/hyperkitty/list/flashrom@flashrom.org/<br />
<br />
* http://www.flashrom.org/pipermail/flashrom/ (Up to Dec. 2018)<br />
<br />
* http://marc.info/?l=flashrom<br />
<br />
* http://www.mail-archive.com/flashrom@flashrom.org/<br />
<br />
* http://blog.gmane.org/gmane.linux.bios.flashrom<br />
<br />
== IRC ==<br />
<br />
You can also contact us via [[IRC]] if you prefer that.<br />
<br />
== Moderation rules ==<br />
<br />
If your mail is too big (the current limit is 256 kB) or if you're not on the subscriber list, your mail will be held for moderation. If your mail contains any BIOS images or F segment dumps (instead of links which are fine), the mail will be rejected for legal reasons (we do not have the right to distribute BIOS images).<br />
<br />
[[Mailinglist/Moderation howto|Moderation howto]] for moderators.</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2409Development Guidelines2019-12-21T21:06:55Z<p>Dhendrix: /* Sending a patch */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'')<br />
and will only add backported fixes to the release.<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]. When sending a patch via the mailing list, send it in-line instead of as an attachment so that reviewers can easily comment on specific parts of it.<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [https://www.flashrom.org/Development_Guidelines#Merging_to_branches Merging to branches]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2408Development Guidelines2019-12-08T22:13:24Z<p>Dhendrix: /* Release branches (e.g. 1.0.x) */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'')<br />
and will only add backported fixes to the release.<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [https://www.flashrom.org/Development_Guidelines#Merging_to_branches Merging to branches]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2405Development Guidelines2019-12-01T09:17:33Z<p>Dhendrix: /* Using Github */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [https://www.flashrom.org/Development_Guidelines#Merging_to_branches Merging to branches]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2404Development Guidelines2019-12-01T09:16:20Z<p>Dhendrix: /* Sending a patch */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [https://www.flashrom.org/Development_Guidelines#Using_Github Using Github].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [[Merging to branches]]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2403Development Guidelines2019-12-01T09:12:03Z<p>Dhendrix: </p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [[Development Guidelines:Using Github]].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged (See: [[Merging to branches]]).<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2402Development Guidelines2019-12-01T09:03:04Z<p>Dhendrix: /* Sending a patch */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [[Using Github]].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged.<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2401Development Guidelines2019-12-01T03:56:49Z<p>Dhendrix: /* Set up your Gerrit account on review.coreboot.org */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [[UsingGithub|Using Github]].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged.<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github credentials.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2400Development Guidelines2019-12-01T03:46:40Z<p>Dhendrix: /* Using Github */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [[UsingGithub|Using Github]].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged.<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials. Here's how to do this:<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github account OAuth2 account.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://'''<gerrit_username>'''@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new local branch that tracks upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
<br />
4. Cherry-pick to new local branch: ''git cherry-pick <your_commit_from_local_branch>''<br />
<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
If successful, the Gerrit URL for your patch will be shown in the output.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2399Development Guidelines2019-12-01T03:42:42Z<p>Dhendrix: /* Patch submission */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
2. Via our [[Mailinglist|mailing list]]<br />
<br />
3. Github users: See [[UsingGithub|Using Github]].<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Using Github ==<br />
<br />
The official Flashrom mirror on Github is: https://github.com/flashrom/flashrom<br />
<br />
All changes go thru Gerrit on review.coreboot.org before being merged. As a convenience, pull requests may be used for small patches such as adding support for a flash chip or simple compilation fixes (usually <10 lines), however a maintainer will need to see the patch and push it to the upstream review server before it can be merged.<br />
<br />
The quickest and best way to get your patch reviewed and merged is by sending it to review.coreboot.org. You may use your Github/OAuth2 credentials, however there are some brief steps needed to get set up for this.<br />
<br />
=== Set up your Gerrit account on review.coreboot.org ===<br />
<br />
1. Go to https://review.coreboot.org/login and sign in using your Github account OAuth2 account.<br />
<br />
2. Edit your settings by clicking on the gear icon in the upper right corner.<br />
<br />
3. Set your Gerrit username (this is different from your Github username).<br />
<br />
4. Add an e-mail address so that Gerrit can send notifications to you about your patch.<br />
<br />
5. Upload an SSH public key, or click the button to generate an HTTPS password<br />
<br />
=== Push your patch ===<br />
<br />
1. Install Change-Id hook: ''gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <gerrit_username>@review.coreboot.org:hooks/commit-msg ${gitdir}/hooks/''<br />
<br />
2. Add upstream as a remote:<br />
If using SSH: ''git remote add -f upstream ssh://<gerrit_username>@review.coreboot.org:29418/flashrom.git''.<br />
If using HTTPS: ''git remote add -f upstream https://review.coreboot.org/flashrom''<br />
<br />
3. Check out a new branch tracking upstream/master: ''git checkout -b <branch_name> upstream/master''<br />
4. Cherry-pick: ''git cherry-pick <your_commit_from_local_branch>''<br />
5. Push to gerrit: ''git push upstream HEAD:refs/for/master%topic=my_wonderful_patch''. If using HTTPS you will be prompted for the username and password you set in the Gerrit UI.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2396Development Guidelines2019-09-18T05:02:32Z<p>Dhendrix: /* Sign-off Procedure */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the Developer's Certificate of Origin 1.1 printed below. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You must use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name lack provenance and cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2395Development Guidelines2019-09-17T06:22:30Z<p>Dhendrix: /* Commit message */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
may skip the long description if the short description is sufficient,<br />
for example "flashchips: Add FOO25Q128" to add FOO25Q128 chip support.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2394Development Guidelines2019-09-17T06:16:49Z<p>Dhendrix: /* Commit message */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line. You<br />
You may skip the long description if the short description is<br />
sufficient. An example is adding a single flash chip, such as<br />
"flashchips: Add FOO25Q128".<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. For non-trivial changes you must explain<br />
what your patch does, why, and how it was tested.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
<span style="color:red">Signed-off-by: Your Name <your@domain></span><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2393Development Guidelines2019-09-17T06:09:11Z<p>Dhendrix: /* Commit message */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is separated from the summary by a blank line.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. You should explain what and why your patch<br />
does, and any interesting notes about testing.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
Signed-off-by: Your Name <your@domain><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2392Development Guidelines2019-09-17T06:08:36Z<p>Dhendrix: /* Commit message */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 80 characters. It is seeparated from the summary by a blank line.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. You should explain what and why your patch<br />
does, and any interesting notes about testing.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
Signed-off-by: Your Name <your@domain><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2391Development Guidelines2019-09-17T06:07:12Z<p>Dhendrix: /* Commit message */</p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is seeparated from the summary by a blank line.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. You should explain what and why your patch<br />
does, and any interesting notes about testing.<br />
<br />
Finally, follow the [[#Sign-off Procedure]] to add your sign-off!<br />
<br />
Signed-off-by: Your Name <your@domain><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrixhttps://wiki.flashrom.org/index.php?title=Development_Guidelines&diff=2390Development Guidelines2019-09-17T06:06:20Z<p>Dhendrix: </p>
<hr />
<div>= Branches =<br />
<br />
=== Historical ===<br />
<br />
Till the release of flashrom 0.9.9 there was basically a single branch<br />
(trunk) where linear development happened. After 0.9.9 it was decided<br />
to switch to Git and a two branch model, a ''stable'' and a ''staging''<br />
branch. This led to some confusion and as nobody who had access to the<br />
''stable'' branch had the time to work on it, development continued<br />
about one year after the 0.9.9 release on a ''staging'' branch at<br />
coreboot.org. Despite its name, we strived to keep flashrom's quality<br />
and hoped that everything would be merged to ''stable'' once work<br />
continues there.<br />
<br />
=== ''master'' branch ===<br />
<br />
The historical ''staging'' branch was finally renamed to ''master''.<br />
As usual there is no quality promise for the state of the code on the<br />
''master'' branch. Even though we will try to keep the regression<br />
rate as low as possible, the main purpose of the branch is to merge<br />
new commits and make them available to a broader audience for testing.<br />
<br />
=== Release branches (e.g. ''1.0.x'') ===<br />
<br />
Branching for a new release can happen at any point in time when a<br />
commit (branch point) on ''master'' seems to be in good shape and was<br />
reasonably tested after previous invasive changes. Between the branch<br />
point and the release, every fix pushed for ''master'' for a problem<br />
that also persists on the release branch shall be backported. The same<br />
also applies after the release for the latest release branch and,<br />
optionally, for any earlier release branch that is still maintained<br />
for other reasons (e.g. part of a long term distribution).<br />
<br />
Whenever a release branch has no further unmerged commits in queue<br />
and is not awaiting backported fixes, a release candidate (RC) can be<br />
tagged on that branch. This can also be the original branch point. The<br />
RC shall undergo extensive build tests and be publicly advertised as<br />
ready for testing. Not less than three days after the last RC that<br />
included code changes, a release can be tagged if no regressions<br />
showed up.<br />
<br />
Release-branch names follow the pattern '''''<major>.<minor>.x'''''<br />
(e.g. ''1.0.x''). The first release of a branch is tagged<br />
'''''v<major>.<minor>''''', without a point-release number (e.g.<br />
''v1.0''). Every following release from the same branch, will have<br />
a point-release number starting with '''''.1''''' (e.g. ''v1.0.1'').<br />
<br />
Unless the branch point (i.e. last common commit of ''master''<br />
and a release branch) is an RC, it should be tagged as<br />
'''''p<major>.<minor>''''' (e.g. ''p1.0''), to keep track where<br />
we are on the ''master'' branch.<br />
<br />
= Patch submission =<br />
<br />
== Coding style ==<br />
<br />
Flashrom generally follows Linux kernel style: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst<br />
<br />
The notable exception is line length limit. Our guidelines are:<br />
* 80-columns soft limit for most code and comments. This is to encourage simple design and concise naming.<br />
<br />
* 112-columns hard limit. Use this to reduce line breaks in cases where they harm grep-ability or overall readability, such as print statements and function signatures. Don't abuse this for long variable/function names or deep nesting.<br />
<br />
* Tables are the only exception to the hard limit and may be as long as needed for practical purposes.<br />
<br />
== Sending a patch ==<br />
<br />
'''Before submitting a patch for review, put your [[#Sign-off Procedure|Signed-off-by line]] in the commit message.'''<br />
<br />
Currently there are three ways to submit patches:<br />
<br />
1. Via our [[Mailinglist|mailing list]]<br />
<br />
2. Via [https://review.coreboot.org/#/q/project:flashrom gerrit on coreboot.org], i.e. ''git push origin HEAD:refs/for/master'' ([https://coreboot.org/Git see instructions])<br />
<br />
3. Via pull request on [https://github.com/flashrom/flashrom/ flashrom's github mirror]<br />
<br />
Our guidelines borrow heavily from [http://www.coreboot.org/Development_Guidelines the coreboot development guidelines], and most of them apply to flashrom as well. The really important part is about the Signed-off-by procedure which is quoted [[#Sign-off Procedure|below]].<br />
<br />
We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. See also [[Random notes#Command_set_secrets|Command set secrets]].<br />
<br />
The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones as soon as possible, but we have quite high standards regarding code quality.<br />
<br />
If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.<br />
<br />
For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.<br />
<br />
== Commit message ==<br />
<br />
Commit messages shall have the following format:<br />
<component>: Short description (up to 72 characters)<br />
<br />
This is a long description. Max width of each line in the description<br />
is 72 characters. It is seeparated from the summary by a blank line.<br />
<br />
You may have multiple paragraphs in the long description, but please<br />
do not write a novel here. You should explain what and why your patch<br />
does, and any interesting notes about testing.<br />
<br />
Finally, follow the [[Sign-off Procedure]] to add your sign-off!<br />
<br />
Signed-off-by: Your Name <your@domain><br />
<br />
<br />
=== Sign-off Procedure ===<br />
<br />
We employ a similar sign-off procedure [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html as the Linux kernel developers] do.<br />
Add a note such as<br />
Signed-off-by: Random J Developer <random@developer.example.org><br />
to your email/patch if you agree with the following Developer's Certificate of Origin 1.1. Read [https://lkml.org/lkml/2004/5/23/10 this post on the LKML] for rationale (spoiler: SCO).<br />
<br />
<span style="color:red">You have to use your real name in the Signed-off-by line and in any copyright notices you add.</span> Patches without an associated real name cannot be committed!<br />
<br />
'''Developer's Certificate of Origin 1.1:'''<br />
<br />
By making a contribution to this project, I certify that:<br /><br />
(a) The contribution was created in whole or in part by me and I have<br />
the right to submit it under the open source license indicated in the file; or<br /><br />
(b) The contribution is based upon previous work that, to the best of my<br />
knowledge, is covered under an appropriate open source license and I have the<br />
right under that license to submit that work with modifications, whether created<br />
in whole or in part by me, under the same open source license (unless I am<br />
permitted to submit under a different license), as indicated in the file; or<br /><br />
(c) The contribution was provided directly to me by some other person who<br />
certified (a), (b) or (c) and I have not modified it; and<br /><br />
(d) In the case of each of (a), (b), or (c), I understand and agree that<br />
this project and the contribution are public and that a record of the contribution<br />
(including all personal information I submit with it, including my sign-off) is<br />
maintained indefinitely and may be redistributed consistent with this project or the<br />
open source license indicated in the file.<br />
<br />
<small>Note: The [http://web.archive.org/web/20070306195036/http://osdlab.org/newsroom/press_releases/2004/2004_05_24_dco.html Developer's Certificate of Origin 1.1] is licensed under the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].</small><br />
<br />
= Reviews =<br />
<br />
All patches finally have to go through Gerrit. Though, if the author prefers, the actual reviewing process can also take place on the mailing list or on github.<br />
<br />
All contributions should receive at least a preliminary review within one week of submission by some flashrom developer (if that doesn't happen in time, please be patient).<br />
At minimum this should include a broad indication of acceptance or rejection of...<br />
* the idea/rationale/motivation,<br />
* the implementation<br />
respectively.<br />
<br />
In general, reviews should focus on the architectural changes and things that affect flashrom as a whole.<br />
This includes (but is by no means limited to) changes in APIs and types, safety, portability, extensibility, and maintainability.<br />
The purpose of reviews is not to create perfect patches, but to steer development in the right direction and produce consensus within the community.<br />
The goal of each patch should be to improve the state of the project - it does not need to fix all problems of the respective field perfectly.<br />
NB: New contributors may need more detailed advices and should be told about minor issues like formatting problems more precisely.<br />
The result of a review should either be an accepted patch or a guideline how the existing code should be changed to be eventually accepted.<br />
<br />
== Adding/reviewing a new flash chip ==<br />
# Get the datasheet of the exact type of chip.<br />
# Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.<br />
# First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already<br />
#* If it does but is named after a different chip,<br />
#*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).<br />
#* If it does and the name matches too,<br />
#*:the chip is either already added or only the ID was added and you should use that define.<br />
#* If it does not,<br />
#*:then you should add it conforming to the standards/comments in the file.<br />
#: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h.<br />
# If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)<br />
# Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.<br />
# <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.<br />
# We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.<br />
# <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.<br />
# <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.<br />
# <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).<br />
# <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).<br />
## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.<br />
## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).<br />
# <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.<br />
# <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.<br />
# <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.<br />
# <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.<br />
# The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.<br />
<br />
= Merging to branches =<br />
<br />
Merging to branches is limited to the "flashrom developers" group on<br />
Gerrit. This means every patch reviewed somewhere else (e.g. mailing<br />
list or github) must finally be pushed to Gerrit. The following rules<br />
apply, some are already enforced by Gerrit:<br />
<br />
* Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.<br />
* Except, if a commit is authored by more than one person, each author may +2 the other author's changes.<br />
* Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).<br />
* Finally, before hitting ''Submit'', one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).</div>Dhendrix