September 2023 - flashrom-gerrit

[M] Change in flashrom[main]: doc: Convert release notes for v1.3
by Anastasia Klimchuk (Code Review) 25 Sep '23

25 Sep '23

Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/78116?usp=email ) Change subject: doc: Convert release notes for v1.3 ...................................................................... doc: Convert release notes for v1.3 Change-Id: I5b66a957249c3025715eff2b00f1be9eb0d36096 Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> --- M doc/index.rst A doc/release_notes/index.rst A doc/release_notes/v_1_3.rst 3 files changed, 219 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/16/78116/1 diff --git a/doc/index.rst b/doc/index.rst index 1943934..983bd7d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ dev_guide/index classic_cli_manpage contact + release_notes/index about_flashrom/index how_to_add_docs documentation_license diff --git a/doc/release_notes/index.rst b/doc/release_notes/index.rst new file mode 100644 index 0000000..a8ef58f --- /dev/null +++ b/doc/release_notes/index.rst @@ -0,0 +1,7 @@ +Release notes +============= + +.. toctree:: + :maxdepth: 1 + + v_1_3 diff --git a/doc/release_notes/v_1_3.rst b/doc/release_notes/v_1_3.rst new file mode 100644 index 0000000..4bd9c0a --- /dev/null +++ b/doc/release_notes/v_1_3.rst @@ -0,0 +1,211 @@ +=============== +v1.3 (Feb 2023) +=============== + +It has been almost three years since our last release. All this time we have been working +on enhancing the flashrom code base. This new release comes with a lot of new features, programmers, +improvements, and bug fixes. A detailed but not exhaustive change log is presented below. + +New major user-visible features +=============================== + +* Support for the Linux I2C subsystem +* Option to read/write only region to/from ROM is renamed to :code:`--include` (:code:`--image` option + is deprecated and exist only for back compatibility). An optional sub-parameter + (:code:`--include <region>[:<file>]`) to allow building the image to be written from multiple files is added +* Support different SPI modes (Dual IO, Quad IO, Normal, Fast Read) for AMD’s chipsets (>= Bolton) +* Support for Write Protection configuration (:code:`--wp-disable, --wp-enable, --wp-list, --wp-status, --wp-range, --wp-region`) +* Add SPI SR2/SR3 read/write support +* The Intel chipset detection has been improved +* Bus Pirate SPI + + * New parameter to control the external Vcc state (:code:`psus=<on|off>`) + +* Dediprog + + * Add 4BA support on SF600 protocol version 3 + +* Dummyflasher + + * New parameter to allows emulating a bus/chip frequency (:code:`freq`) + * New parameter to emulate flash erase with either 0x00 or 0xff (:code:`erase_to_zero`) + * Add emulation for S25FL128L chip + * SR2, SR3 and WP is emulated for W25Q128FV + * Emulate variable-size SPI flash chip (4-byte address format is supported) + +* FT2232 SPI dongles + + * New parameter to search FTDI by description, i.e. product string (:code:`description`) + +* SEGGER J-Link and compatible devices + + * New parameter to active the 5V power supply during a flash operation (:code:`power`) + +* Drop "Promontory" architecture (AMD) support +* End Of Life (EOL) for ITE IT85* specific code +* README and man page updated with additional information + +The greatest increase in the speed of operations can be seen on the following programmers: +SPI on Intel NICs, FT2232 SPI dongles + +Libflashrom +=========== + +* Add Write Protect functions to the API +* Add rust Foreign Function Interface bindings for the libflashrom API +* Move documentation from source file to header +* Drop :code:`flashrom_system_info()` +* Drop :code:`flashrom_supported_programmers()` +* Add :code:`flashrom_layout_get_region_range()` +* Declaration change from :code:`flashrom_layout_read_fmap_from_rom(struct flashrom_layout **const, struct flashctx *const, off_t, size_t)` + to :code:`flashrom_layout_read_fmap_from_rom(struct flashrom_layout **const, struct flashctx *const, size_t, size_t)` +* Allow NULL-pointer argument in :code:`flashrom_flash_release()` + +Infrastructure expansion +======================== + +* Add blackbox test uber-script +* Add E2E tester for a specific chip/chipset combo +* Build script for Jenkins was upgraded and move to repository - :code:`test_build.sh` +* Add a set of Dockerfiles for build testing - :code:`util/manibuilder` +* Add a Nix shell file which is able to compile flashrom - :code:`util/shell.nix` +* Add CMocka unit-test infrastructure into the meson build system (test for drivers available only + if its driver is built). The following tests are included: + + * Core logic tests + * Basic lifecycle for :code:`dediprog, nicrealtek, raiden_debug_spi, parade_lspcon, mediatek_i2c_spi, realtek_mst_i2c_spi` + * Basic lifecycle + chip probe for :code:`dummyflasher, linux_mtd, linux_spi` + * Layout tests (overlapping, sanity checks, invalid range/address) + * Erasing/reading/writing/verifying chip tests + * Write Protect tests + * And others! + +* Introduce :code:`MAINTAINERS` file +* Rename :code:`z60_flashrom.rules` to :code:`flashrom_udev.rules` +* Introduce linter for git sign-off-by line +* Move all header files to the new :code:`include` directory. + +Meson +----- + +The minimum version has been increased. Requires at least :code:`0.53.0`. + +* Added build instructions - :code:`Documentation/building.md` +* Allow libflashrom to be built as a static or shared library. +* Add new options: :code:`print_wiki, ich_descriptors_tool, classic_cli` +* Rename :code:`print_wiki` to :code:`classic_cli_print_wiki` option +* Install the man file +* Fix compilation under uClibc-ng +* Add missing config option for J-Link SPI +* Treat warnings as errors and use the same warning options as in Makefile. + +Makefile +-------- + +* Add support for Elbrus (e2k) architecture +* Make pkg-config mandatory to find :code:`libftdi1, libjaylink, libusb1, libpci` + (you still can override detection and set cflags and ldflags manually) +* Merge :code:`compiler, hwlibs, features` targets into :code:`config` target +* Drop :code:`distclean` target +* Drop STANDALONE mode +* Summarize systems with the same CPPFLAGS and LDFLAGS +* Only enable I2C programmers on Linux (linux-specific code) +* Revise C compiler check, utsname and clock_gettime test, detection of Linux specific headers +* Since the NI-845x is a Windows only proprietary library, disable it by default. +* Enable the internal programmer on x86 or linux. +* Fix building on AArch64 NixOS + +Various broken and missing dependencies have been fixed for these two build systems. + +New programmers +=============== + +* Chrome EC based debug tools - SuzyQable, Servo V4, C2D2 & uServo +* Realtek RTD2142 MST +* Parade lspcon USB-C to HDMI protocol translator +* DirtyJTAG (a USB-JTAG firmware for STM32 MCUs) +* MediaTek LCD controller +* Programmers based on FT4233H FTDI +* Kristech KT-LINK +* Variants of STLINK-V3: STLINK-V3E, STLINK-V3S, STLINK-V3 With dual VCP, STLINK-V3 Without MSD +* Intel Gemini Lake PCH +* Intel Meteor Lake PCH +* Intel Elkhart Lake PCH +* Intel Emmitsburg PCH +* Intel Comet Lake-U/400-series PCH +* Intel Tiger Point/500-series PCH +* Intel Jasper Lake PCH +* Intel Alder Lake/600-series PCH +* Intel PCH7 Desktop/Mobile/SFF Sample +* More Intel PCHs variants (Apollo Lake, Cannon Point, Union Point, Lewisburg) + +At some point, flashrom supported ENE LPC interface keyboard controller and Microchip MEC1308 embedded controller. +But they were dropped before the release because the code was no longer maintained by anyone. If you're interested, +take a look at git history. + +New Boards +========== + +* ASUS P3B-F +* Jetway P4MDPT +* ASUS P5W DH Deluxe + +New chips +========= + +* AT25SF128A +* B.25D16A +* BY25Q128AS +* FM25F01 +* FM25F02(A) +* FM25F04(A) +* FM25F005 +* FM25Q08 +* FM25Q16 +* FM25Q32 +* F29C51001B +* GD25LQ128E +* GD25Q256E +* GD25WQ80E +* MX25L12833F +* MX25L12873F +* MX25L3233F +* MX25L5121E +* MX25R3235F +* MX66L1G45G +* S25FL128L +* S25FL128S +* S25FL129P +* S25FL256L +* S25FL256S +* S25FS128S +* S29C51001B +* V29C51001B +* W25Q32JW...M +* W25Q64JV +* W25Q64JW...M +* W25Q256JW +* W25Q256JW_DTR +* W25Q512JV +* W25Q512NW-IM +* W25X05(CL) +* XM25QU64C +* XM25QU128C +* XM25QU256C +* XM25QH64C +* XM25QH128C +* XM25QH256C + +Download +======== + +flashrom 1.3 can be downloaded in various ways: + +Anonymous checkout from the git repository at `<https://review.coreboot.org/flashrom.git>`_ (tag v1.3.0) + +A tarball is available for download at + +`<https://download.flashrom.org/releases/flashrom-v1.3.0.tar.bz2>`_ (GPG signature), +fingerprint: :code:`6E6E F9A0 BA47 8006 E277 6E4C C037 BB41 3134 D111` + +and more in the "Tags" section of CGit at `<https://review.coreboot.org/cgit/flashrom.git>`_ -- To view, visit https://review.coreboot.org/c/flashrom/+/78116?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I5b66a957249c3025715eff2b00f1be9eb0d36096 Gerrit-Change-Number: 78116 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: newchange

1 0

[L] Change in flashrom[main]: doc: Convert write-protect docs to sphinx
by Sergii Dmytruk (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Anastasia Klimchuk, Thomas Heijligen. Sergii Dmytruk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/78113?usp=email ) The change is no longer submittable: All-Comments-Resolved is unsatisfied now. Change subject: doc: Convert write-protect docs to sphinx ...................................................................... Patch Set 1: (3 comments) File doc/user_docs/example_partial_wp.rst: https://review.coreboot.org/c/flashrom/+/78113/comment/36705db7_c3823e74 : PS1, Line 102: control `(sector/block-based)` can be added after `control` because I had to pause for a moment to recall what this is referring to. https://review.coreboot.org/c/flashrom/+/78113/comment/5d8b6a46_d94a9199 : PS1, Line 103: 4 November 2022 Block-based write-protection isn't supported as of today, so the date can be updated accordingly. File doc/user_docs/fw_updates_vs_spi_wp.rst: https://review.coreboot.org/c/flashrom/+/78113/comment/a60ccc64_cb3e24c5 : PS1, Line 62: 4 November 2022) CB:69517 changed the behaviour to use WP code and and then old implementation as a fallback. So the paragraph can be removed (especially if that change is part of v1.3). -- To view, visit https://review.coreboot.org/c/flashrom/+/78113?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Gerrit-Change-Number: 78113 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Comment-Date: Mon, 25 Sep 2023 12:43:26 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Gerrit-MessageType: comment

1 0

[L] Change in flashrom[main]: doc: Convert write-protect docs to sphinx
by Sergii Dmytruk (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Anastasia Klimchuk, Thomas Heijligen. Sergii Dmytruk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/78113?usp=email ) Change subject: doc: Convert write-protect docs to sphinx ...................................................................... Patch Set 1: Code-Review+2 -- To view, visit https://review.coreboot.org/c/flashrom/+/78113?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Gerrit-Change-Number: 78113 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Comment-Date: Mon, 25 Sep 2023 12:20:28 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

[L] Change in flashrom[main]: doc: Convert write-protect docs to sphinx
by Anastasia Klimchuk (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Sergii Dmytruk, Thomas Heijligen. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/78113?usp=email ) Change subject: doc: Convert write-protect docs to sphinx ...................................................................... Patch Set 1: (1 comment) Patchset: PS1: Sergii sorry I forgot to say in my first comment: docs are under CC-BY-4.0 license (the full text is here https://www.flashrom.org/documentation_license.html) hopefully you agree on this. Since you contributed original pages to wiki (not sure what the license was there), it would be ideal if you approve the patch which means you agree with the license. -- To view, visit https://review.coreboot.org/c/flashrom/+/78113?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Gerrit-Change-Number: 78113 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Comment-Date: Mon, 25 Sep 2023 10:26:38 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Gerrit-MessageType: comment

1 0

[L] Change in flashrom[main]: doc: Convert write-protect docs to sphinx
by Anastasia Klimchuk (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Sergii Dmytruk, Thomas Heijligen. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/78113?usp=email ) Change subject: doc: Convert write-protect docs to sphinx ...................................................................... Patch Set 1: (1 comment) Patchset: PS1: Sergii, I have re-formatted these docs from wiki, I kept the same content, maybe you can have a look whether it's still true? I think it is still all true, but there are few paragraphs which say "as of November 2022", maybe those need checking. Thank you! -- To view, visit https://review.coreboot.org/c/flashrom/+/78113?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Gerrit-Change-Number: 78113 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Sergii Dmytruk <sergii.dmytruk(a)3mdeb.com> Gerrit-Comment-Date: Mon, 25 Sep 2023 10:15:29 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Gerrit-MessageType: comment

1 0

[L] Change in flashrom[main]: doc: Convert write-protect docs to sphinx
by Anastasia Klimchuk (Code Review) 25 Sep '23

25 Sep '23

Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/78113?usp=email ) Change subject: doc: Convert write-protect docs to sphinx ...................................................................... doc: Convert write-protect docs to sphinx Updated the information that WP is included in the v1.3 release, and added links to dev guidelines on how to build from head (instead of inlining the instructions). Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> --- M doc/index.rst A doc/user_docs/example_partial_wp.rst A doc/user_docs/fw_updates_vs_spi_wp.rst A doc/user_docs/index.rst 4 files changed, 265 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/13/78113/1 diff --git a/doc/index.rst b/doc/index.rst index 1943934..3a303e1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,6 +10,7 @@ :hidden: dev_guide/index + user_docs/index classic_cli_manpage contact about_flashrom/index diff --git a/doc/user_docs/example_partial_wp.rst b/doc/user_docs/example_partial_wp.rst new file mode 100644 index 0000000..faa5fe5 --- /dev/null +++ b/doc/user_docs/example_partial_wp.rst @@ -0,0 +1,191 @@ +=================================== +Example of partial write-protection +=================================== + +This document provides demonstration of how one can protect part of a flash chip +from writing using :code:`flashrom` and its support for manipulating SPI write protection (WP). +This kind of protection requires changing connection of WP pin of the chip to prevent +any attempt of disabling the protection by software alone. + +Not to be confused with protection by flash controller of your motherboard (PCH protection). + +Version of flashrom +=================== + +Write-protect manipulation functionality is included in flashrom since release v1.3.0. +If for any reasons you need the latest code from head, you might need to build :code:`flashrom` +from scratch. The following docs describe how to do this :doc:`/dev_guide/building_from_source` and +:doc:`/dev_guide/building_with_make`. See also :doc:`/dev_guide/development_guide`. + +Alternatively, your operating system might provide development version of :code:`flashrom` as a package. + +Programmer support of WP +======================== + +Not all programmers support manipulating WP configuration. A suitable programmer must either +provide a dedicated API for working with WP or give sufficiently comprehensive access to the +interface of the flash chip. + +In particular, *internal* programmer on Intel platforms might allow only limited access to WP +feature of chips or effectively deny it. Read "Intel chipsets" section of flashrom's manpage +for details on how you can try choosing sequencing type to possibly make WP work for you. + +In some cases external flashing might be the only option and you need to unscrew your device, +find the chip, connect it to another device through a suitable adapter and finally be able +to configure it as you wish. + +Chip support in flashrom +======================== + +There is a great variety of chips with some not supporting write protection at all and others +doing it in their own peculiar way of which :code:`flashrom` has no idea. So the first thing to do is +to make sure that :code:`flashrom` knows how WP works for your chip and chipset doesn't get in the way. +Run a command like (adjust this and similar commands below if you're not using *internal* programmer +or need to specify other options):: + + flashrom --programmer internal --wp-status: + +Seeing this output line would mean that :code:`flashrom` doesn't know how to use WP feature of the chip you have:: + + Failed to get WP status: WP operations are not implemented for this chip + +Otherwise the output might contain something similar to this:: + + Protection range: start=0x00000000 length=0x00000000 (none) + Protection mode: disabled + +If so, you can continue with the rest of the instructions. + +Collecting information about the range +====================================== + +You need to know where the area you want to protect starts and ends. The example below assumes +you're trying to protect bootblock stored in CBFS at the end of some :code:`coreboot` firmware. In other cases +it might be a separate file which is put at the beginning of a chip. You need to have an idea of what +you're doing here or have some reliable instructions to follow. + +In this case :code:`cbfstool` can be used to list information about bootblock like this:: + + $ cbfstool rom print | sed -n '2p; /bootblock/p' + Name Offset Type Size Comp + bootblock 0x3ef100 bootblock 36544 none + +However, the offset is relative to the start of CBFS region, so we also need to find out offset of CBFS:: + + $ cbfstool rom layout | grep CBFS + 'COREBOOT' (CBFS, size 4161536, offset 12615680) + +Now we can calculate: + +* start offset (CBFS offset + 64 + bootblock offset):: + + 12615680 + 64 + 0x3ef100 = 0xff7140 + (printf "%#x\n" $(( 12615680 + 64 + 0x3ef100 ))) + +* end offset (start offset + bootblock size - 1):: + + 0xff7140 + 36544 - 1 = 0xffffff + (printf "%#x\n" $(( 0xff7140 + 36544 - 1 ))) + +Thus we need to write-protect the smallest area that covers the range from :code:`0xff7140` to :code:`0xffffff` +(both bounds are inclusive). + +“64” in the computation of start offset is offset of booblock data. Unfortunately, current tooling +doesn't provide a reliable way of determining actual offset, but 64 is the typical “extra offset” one needs +to add to account for file metadata of CBFS (otherwise it can be its multiple 128 or bigger). Bootblock +should normally end at the last byte of ROM on x86 systems, giving you a way to test the result of computations. + +Finding a matching range +======================== + +In most chips the list of supported ranges is fixed and you can't specify an arbitrary one. Some others +allow more fine-grained control, but that feature is not supported even by development version of flashrom +as of now (4 November 2022). + +Obtain list of supported ranges from which we'll pick the best match:: + + $ flashrom --programmer internal --wp-list + ... + Available protection ranges: + start=0x00000000 length=0x00000000 (none) + start=0x00000000 length=0x00001000 (lower 1/4096) + start=0x00fff000 length=0x00001000 (upper 1/4096) + start=0x00000000 length=0x00002000 (lower 1/2048) + start=0x00ffe000 length=0x00002000 (upper 1/2048) + start=0x00000000 length=0x00004000 (lower 1/1024) + start=0x00ffc000 length=0x00004000 (upper 1/1024) + start=0x00000000 length=0x00008000 (lower 1/512) + start=0x00ff8000 length=0x00008000 (upper 1/512) + start=0x00000000 length=0x00040000 (lower 1/64) + start=0x00fc0000 length=0x00040000 (upper 1/64) + start=0x00000000 length=0x00080000 (lower 1/32) + start=0x00f80000 length=0x00080000 (upper 1/32) + start=0x00000000 length=0x00100000 (lower 1/16) + start=0x00f00000 length=0x00100000 (upper 1/16) + start=0x00000000 length=0x00200000 (lower 1/8) + start=0x00e00000 length=0x00200000 (upper 1/8) + start=0x00000000 length=0x00400000 (lower 1/4) + start=0x00c00000 length=0x00400000 (upper 1/4) + start=0x00000000 length=0x00800000 (lower 1/2) + start=0x00800000 length=0x00800000 (upper 1/2) + start=0x00000000 length=0x00c00000 (lower 3/4) + start=0x00400000 length=0x00c00000 (upper 3/4) + start=0x00000000 length=0x00e00000 (lower 7/8) + start=0x00200000 length=0x00e00000 (upper 7/8) + start=0x00000000 length=0x00f00000 (lower 15/16) + start=0x00100000 length=0x00f00000 (upper 15/16) + start=0x00000000 length=0x00f80000 (lower 31/32) + start=0x00080000 length=0x00f80000 (upper 31/32) + start=0x00000000 length=0x00fc0000 (lower 63/64) + start=0x00040000 length=0x00fc0000 (upper 63/64) + start=0x00000000 length=0x00ff8000 (lower 511/512) + start=0x00008000 length=0x00ff8000 (upper 511/512) + start=0x00000000 length=0x00ffc000 (lower 1023/1024) + start=0x00004000 length=0x00ffc000 (upper 1023/1024) + start=0x00000000 length=0x00ffe000 (lower 2047/2048) + start=0x00002000 length=0x00ffe000 (upper 2047/2048) + start=0x00000000 length=0x00fff000 (lower 4095/4096) + start=0x00001000 length=0x00fff000 (upper 4095/4096) + start=0x00000000 length=0x01000000 (all) + +Pick a range by scanning the list in the top down order (because the smaller ranges come first): + + * if bootblock is at the start of a chip, look for the first lower range whose length is greater than the end offset + * if bootblock is at the end of a chip, look for the first upper range which starts before or at the start offset + * mind that you're unlikely to find an ideal match and will probably protect more than you need; this is fine + if that's just an empty space, but can cause trouble with future updates if that's some data or metadata which + changes with every release (see :doc:`fw_updates_vs_spi_wp` for more on this) + +This is the first upper range starting before 0xff7140:: + + start=0x00fc0000 length=0x00040000 (upper 1/64) + +It covers :code:`0x00fc0000 - 0x00ffffff` which includes our bootblock. This area takes up 256 KiB, about 7 times bigger +than our bootblock, but there is no better choice in this case and output of :code:`cbfstool rom layout` shows +that we additionally include a part of 876 KiB empty space which will hopefully remain there in future firmware versions +(it's a good idea to check before a firmware update). + +Protection setup +================ + +The following command sets the range and enables WP at the same time, the values are taken from the chosen range above:: + + flashrom --programmer internal --wp-range=0x00fc0000,0x00040000 --wp-enable + +You can set the range and change WP status independently as well if needed (just specify one :code:`--wp-*` option at a time). +Make sure that hardware protection is off (state of :code:`W#`/:code:`W/` pin of the chip) or you won't be able +to change WP configuration. + +On success, the output of the above command will include such lines:: + + Enabled hardware protection + Activated protection range: start=0x00fc0000 length=0x00040000 (upper 1/64) + +**Caveat:** :code:`flashrom` automatically tries to disable WP before any operation on a chip (read, write, erase, verify), +so double-check status of WP before changing state of WP pin on your chip! + +Verifying hardware protection +============================= + +Once you're happy with the configuration and changed state of WP pin, you can try disabling WP +using :code:`flashrom --wp-disable` to make sure that it fails now. diff --git a/doc/user_docs/fw_updates_vs_spi_wp.rst b/doc/user_docs/fw_updates_vs_spi_wp.rst new file mode 100644 index 0000000..cc65b50 --- /dev/null +++ b/doc/user_docs/fw_updates_vs_spi_wp.rst @@ -0,0 +1,65 @@ +======================================== +Firmware updates vs SPI write-protection +======================================== + +Enabling write-protection of any kind is meant to obstruct changing data, but it also limits +what you can do to the part of firmware that's still writable. This document is meant to cover +some of the origins of such limitations and situations which might arise after +part of a flash chip has been protected. + +Firmware updates after locking bootblock +======================================== + +This section is primarily concerned with :code:`coreboot` with bootblock being protected from writing, +but similar problems can happen for any kind of firmware. + +Risks of partial updates +------------------------ + +Partial updates can produce an unbootable image if an old bootblock doesn't work with a more recent +version of :code:`coreboot`. This can be manifested in various ways ranging from an old bootblock not being able +to find new romstage to system booting successfully but data in :code:`coreboot` tables being mangled or incomplete. + +The incompatibilities might happen when switching version of firmware or even when using the same version +with a slightly different configuration. + +Another thing that can potentially cause trouble is CBFS layout. When bootblock is part of CBFS, +it doesn't necessarily have a fixed address, moreover it can change location as well if it depends on file size +(when bootblock's last byte must be the last byte of the image, which is the case on x86). If newer bootblock +is smaller such that an old WP range now covers bootblock and some other file, this file won't be fully updated +due to write-protection, potentially resulting in a corrupt image. Luckily, when bootblock is the last file +it's normally preceded by a significant amount of empty space, which won't let this situation to occur. + +On top of that, last 4 bytes of the image contain offset to the master header of CBFS. Depending on +the :code:`coreboot` version this offset might be crucial for the loading of romstage, in which case moving CBFS +within the image without updating the offset (when it's locked by WP) can also prevent the system from booting. + +Recovering from a broken state +------------------------------ + +Since broken flash won't let the system to boot, the way to fix it is to flash the chip externally by connecting +it to a different device. A possible alternative could be to have a backup flash created beforehand and swapping +it for the broken one (not very applicable if swapping doesn't require soldering). There are also some mainboards +with dual flash chips one of which acts as a backup that can be restored by holding power on button long enough. + +Flashing whole firmware image +============================= + +The function of the hardware protection mechanism (:code:`W#` or :code:`W/` pin of flash chips) is to lock state of +software protection thus preventing it from being disabled. After the chip is physically unlocked by changing +the state of the pin, the state of the write protection doesn't change. However, in this state the protection +can be easily turned off programmatically, which is what :code:`flashrom` tries to do before performing an operation on a chip. + +In other words, changing state of the WP pin might be enough to be able to flash the chip in full. +If :code:`flashrom` errors or you don't want to rely on the automatic behaviour, you can try to +explicitly disable the protection by running :code:`flashrom` like this:: + + flashrom --wp-disable + +If you need to pass extra parameters to flash your chip (e.g., programmer or chip name), add them to the above command +(order of such parameters shouldn't matter). + +Mind that as of now (4 November 2022) :code:`flashrom` uses different code for temporarily disabling protection automatically +before an operation (the state is restored afterwards) and for handling :code:`--wp-disable`. This means that effects on +write protection can be different depending on which code changes it, which is why you should know about existence +of both of these code paths. diff --git a/doc/user_docs/index.rst b/doc/user_docs/index.rst new file mode 100644 index 0000000..b4cca34 --- /dev/null +++ b/doc/user_docs/index.rst @@ -0,0 +1,8 @@ +Users documentation +=================== + +.. toctree:: + :maxdepth: 1 + + fw_updates_vs_spi_wp + example_partial_wp -- To view, visit https://review.coreboot.org/c/flashrom/+/78113?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I223f1aa5f4531b28b04bcfcecd9becfa7899c3d9 Gerrit-Change-Number: 78113 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: newchange

1 0

[S] Change in flashrom[main]: tree: Rename master branch to main
by Stefan Reinauer (Code Review) 25 Sep '23

25 Sep '23

Stefan Reinauer has submitted this change. ( https://review.coreboot.org/c/flashrom/+/75706?usp=email ) Change subject: tree: Rename master branch to main ...................................................................... tree: Rename master branch to main Change-Id: I8f4a377735f3f6ab4a22006949ff294a218bdf22 Signed-off-by: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> Reviewed-on: https://review.coreboot.org/c/flashrom/+/75706 Reviewed-by: Anastasia Klimchuk <aklm(a)chromium.org> --- M doc/dev_guide/development_guide.rst M util/manibuilder/Makefile M util/manibuilder/README.md 3 files changed, 5 insertions(+), 5 deletions(-) Approvals: Stefan Reinauer: Verified Anastasia Klimchuk: Looks good to me, approved diff --git a/doc/dev_guide/development_guide.rst b/doc/dev_guide/development_guide.rst index 40837a9..bdbee37 100644 --- a/doc/dev_guide/development_guide.rst +++ b/doc/dev_guide/development_guide.rst @@ -32,7 +32,7 @@ * If using https: :code:`git remote add -f upstream https://review.coreboot.org/flashrom` * If using ssh: :code:`git remote add -f upstream ssh://<gerrit_username>@review.coreboot.org:29418/flashrom` -#. Check out a new local branch that tracks :code:`upstream/master`: :code:`git checkout -b <branch_name> upstream/master` +#. Check out a new local branch that tracks :code:`upstream/main`: :code:`git checkout -b <branch_name> upstream/main` #. Every patch is required to be signed-off (see also :ref:`sign-off`). Set up your ``user.name`` and ``user.email`` in git config, and don't forget @@ -191,7 +191,7 @@ Pushing a patch --------------- -To push patch to Gerrit, use the follow command: :code:`git push upstream HEAD:refs/for/master`. +To push patch to Gerrit, use the follow command: :code:`git push upstream HEAD:refs/for/main`. * If using HTTPS you will be prompted for the username and password you set in the Gerrit UI. @@ -205,7 +205,7 @@ Adding a topic makes it easy to search "all the patches by the topic", even if the patches have been authored by multiple people. -To add a topic, push with the command: :code:`git push upstream HEAD:refs/for/master%topic=example_topic`. +To add a topic, push with the command: :code:`git push upstream HEAD:refs/for/main%topic=example_topic`. Alternatively, you can add a topic from a Gerrit UI after the patch in pushed (on the top-left section) of patch UI. diff --git a/util/manibuilder/Makefile b/util/manibuilder/Makefile index 98ed30c..b1b982c 100644 --- a/util/manibuilder/Makefile +++ b/util/manibuilder/Makefile @@ -56,7 +56,7 @@ --env IDENT=$(call ident,$*) \ --volume manicache:/home/mani/.ccache \ --name mani_$(call ident,$*) mani/$* \ - "git fetch origin $${TEST_REVISION:-master} && \ + "git fetch origin $${TEST_REVISION:-main} && \ git checkout FETCH_HEAD && \ $(MAKECMD) clean && $(MAKECMD) -j$${CPUS:-1} CC='$(CC)' \ $(if $(STRIP),STRIP='$(STRIP)') \ diff --git a/util/manibuilder/README.md b/util/manibuilder/README.md index b00d618..e2ccd81 100644 --- a/util/manibuilder/README.md +++ b/util/manibuilder/README.md @@ -38,7 +38,7 @@ ------------- The most common use case may be testing the current upstream -*master* branch which is the default for `$(TEST_REVISION)`. +*main* branch which is the default for `$(TEST_REVISION)`. You'll need roughly 20GiB for the *Docker* images. Might look like this: -- To view, visit https://review.coreboot.org/c/flashrom/+/75706?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8f4a377735f3f6ab4a22006949ff294a218bdf22 Gerrit-Change-Number: 75706 Gerrit-PatchSet: 3 Gerrit-Owner: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-MessageType: merged

1 0

[S] Change in flashrom[main]: tree: Rename master branch to main
by Stefan Reinauer (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Anastasia Klimchuk, Patrick Georgi, Thomas Heijligen. Stefan Reinauer has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/75706?usp=email ) Change subject: tree: Rename master branch to main ...................................................................... Patch Set 2: Verified+1 -- To view, visit https://review.coreboot.org/c/flashrom/+/75706?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8f4a377735f3f6ab4a22006949ff294a218bdf22 Gerrit-Change-Number: 75706 Gerrit-PatchSet: 2 Gerrit-Owner: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Comment-Date: Sun, 24 Sep 2023 23:15:33 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

[S] Change in flashrom[main]: tree: Rename master branch to main
by Anastasia Klimchuk (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Patrick Georgi, Stefan Reinauer, Thomas Heijligen. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/75706?usp=email ) Change subject: tree: Rename master branch to main ...................................................................... Patch Set 2: Code-Review+2 -- To view, visit https://review.coreboot.org/c/flashrom/+/75706?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8f4a377735f3f6ab4a22006949ff294a218bdf22 Gerrit-Change-Number: 75706 Gerrit-PatchSet: 2 Gerrit-Owner: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Attention: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Comment-Date: Sun, 24 Sep 2023 23:13:06 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

[S] Change in flashrom[main]: tree: Rename master branch to main
by Stefan Reinauer (Code Review) 25 Sep '23

25 Sep '23

Attention is currently required from: Anastasia Klimchuk, Patrick Georgi, Thomas Heijligen. Stefan Reinauer has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/75706?usp=email ) Change subject: tree: Rename master branch to main ...................................................................... Patch Set 2: (1 comment) Patchset: PS2: > I think this patch can be reviewed/approved now, but it needs to be submitted only after the branch […] Done -- To view, visit https://review.coreboot.org/c/flashrom/+/75706?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8f4a377735f3f6ab4a22006949ff294a218bdf22 Gerrit-Change-Number: 75706 Gerrit-PatchSet: 2 Gerrit-Owner: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Patrick Georgi <patrick(a)coreboot.org> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Comment-Date: Sun, 24 Sep 2023 23:11:29 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: comment

1 0

2024

2023

2022

2021

2020

2019

2018

2017

flashrom-gerrit September 2023