Attention is currently required from: David Hendricks.
Hello David Hendricks, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/flashrom/+/83753?usp=email
to look at the new patch set (#2).
The following approvals got outdated and were removed:
Verified+1 by build bot (Jenkins)
Change subject: doc: Convert the doc for MSI JSPI1
......................................................................
doc: Convert the doc for MSI JSPI1
The doc converted from
https://wiki.flashrom.org/MSI_JSPI1
Change-Id: Idd215a3a3a4d62629803a71d360755c43c1ab599
Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org>
---
M doc/user_docs/index.rst
A doc/user_docs/msi_jspi1.rst
2 files changed, 53 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/53/83753/2
--
To view, visit https://review.coreboot.org/c/flashrom/+/83753?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: newpatchset
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Idd215a3a3a4d62629803a71d360755c43c1ab599
Gerrit-Change-Number: 83753
Gerrit-PatchSet: 2
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: David Hendricks <david.hendricks(a)gmail.com>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: David Hendricks <david.hendricks(a)gmail.com>
Attention is currently required from: Nikolai Artemiev, Stefan Reinauer, Victor Lim.
Anastasia Klimchuk has posted comments on this change by Victor Lim. ( https://review.coreboot.org/c/flashrom/+/83717?usp=email )
Change subject: flashchips: add GD25LF256F
......................................................................
Patch Set 1:
(4 comments)
Commit Message:
https://review.coreboot.org/c/flashrom/+/83717/comment/35621545_f5365721?us… :
PS1, Line 13: I will have to email you the datasheet.
> Yes, that would be great! I will wait for you to send me a datasheet.
I got the datasheet, thank you! You can remove this sentence from commit message.
https://review.coreboot.org/c/flashrom/+/83717/comment/04a502db_2c8d0d2c?us… :
PS1, Line 15: protestion
A typo: protestion -> protection
File flashchips.c:
https://review.coreboot.org/c/flashrom/+/83717/comment/081658fe_7afdb349?us… :
PS1, Line 6736: GD25LF256F
Could you please move this definition to be after GD25LF128E, in the same order as you did for IDs in flashchips.h ?
GD25LF128E definition is currently around line 6540
https://review.coreboot.org/c/flashrom/+/83717/comment/374aeb51_840025c2?us… :
PS1, Line 6785: BP4
Lets put the full comment here, as usual:
> Called BP4 in datasheet, acts like TB
--
To view, visit https://review.coreboot.org/c/flashrom/+/83717?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: I21a71606476e823faa38a7920aa2b10e25d68d26
Gerrit-Change-Number: 83717
Gerrit-PatchSet: 1
Gerrit-Owner: Victor Lim <vlim(a)gigadevice.com>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Nikolai Artemiev <nartemiev(a)google.com>
Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Victor Lim <vlim(a)gigadevice.com>
Gerrit-Attention: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Attention: Nikolai Artemiev <nartemiev(a)google.com>
Gerrit-Comment-Date: Mon, 05 Aug 2024 09:48:06 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Comment-In-Reply-To: Anastasia Klimchuk <aklm(a)chromium.org>
Attention is currently required from: Anastasia Klimchuk, Stefan Reinauer.
Peter Marheine has posted comments on this change by Anastasia Klimchuk. ( https://review.coreboot.org/c/flashrom/+/83762?usp=email )
Change subject: doc: Add doc describing release process
......................................................................
Patch Set 1: Code-Review+2
--
To view, visit https://review.coreboot.org/c/flashrom/+/83762?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Id6aacf5ef3879a5e236759e7a4a6af3cf7cc0a00
Gerrit-Change-Number: 83762
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Peter Marheine <pmarheine(a)chromium.org>
Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Comment-Date: Sun, 04 Aug 2024 23:36:58 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
Attention is currently required from: Anastasia Klimchuk.
Peter Marheine has posted comments on this change by Anastasia Klimchuk. ( https://review.coreboot.org/c/flashrom/+/83761?usp=email )
Change subject: doc: Fix the link to In-System programming doc
......................................................................
Patch Set 1: Code-Review+2
--
To view, visit https://review.coreboot.org/c/flashrom/+/83761?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Ic82be2b926b0d3a9de7d4b030bbef31c1b3746fb
Gerrit-Change-Number: 83761
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Peter Marheine <pmarheine(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Comment-Date: Sun, 04 Aug 2024 23:35:18 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
Anastasia Klimchuk has posted comments on this change by Anastasia Klimchuk. ( https://review.coreboot.org/c/flashrom/+/83762?usp=email )
Change subject: doc: Add doc describing release process
......................................................................
Patch Set 1:
(1 comment)
Patchset:
PS1:
Ready for review, but will need to wait for CB:83673 to be submitted.
--
To view, visit https://review.coreboot.org/c/flashrom/+/83762?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Id6aacf5ef3879a5e236759e7a4a6af3cf7cc0a00
Gerrit-Change-Number: 83762
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Comment-Date: Sun, 04 Aug 2024 08:00:33 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/83762?usp=email )
Change subject: doc: Add doc describing release process
......................................................................
doc: Add doc describing release process
Change-Id: Id6aacf5ef3879a5e236759e7a4a6af3cf7cc0a00
Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org>
---
M doc/dev_guide/index.rst
A doc/dev_guide/release_process.rst
M doc/how_to_support_flashrom.rst
3 files changed, 103 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/62/83762/1
diff --git a/doc/dev_guide/index.rst b/doc/dev_guide/index.rst
index 57cd846..6aa65be 100644
--- a/doc/dev_guide/index.rst
+++ b/doc/dev_guide/index.rst
@@ -7,3 +7,4 @@
building_from_source
building_with_make
development_guide
+ release_process
diff --git a/doc/dev_guide/release_process.rst b/doc/dev_guide/release_process.rst
new file mode 100644
index 0000000..749779e
--- /dev/null
+++ b/doc/dev_guide/release_process.rst
@@ -0,0 +1,100 @@
+===============
+Release process
+===============
+
+The document describes the technical aspect of making a flashrom release,
+and it assumes that the team of active core maintainers is in agreement to commence the process.
+
+To go through the process, at least two maintainers are needed to be closely involved,
+because it includes sending and approving patches in Gerrit.
+
+Set up the timeline and announce on the mailing list
+====================================================
+
+Decide on the bug-fixing and testing window (3-4 weeks), decide exact dates of start and end of the window,
+and announce it on the mailing list. Ideally make an announcement a few weeks in advance.
+
+During the testing and bug-fixing window only bug fixes are merged, and no new features are added.
+Typically it's fine to push new features for review, and reviews are fine too,
+but merging new features will be delayed until the release is done.
+*This should be very clearly explained in the announcement.*
+
+Start testing and bug-fixing window
+===================================
+
+* Double-check and merge all the patches that are fully ready (see also :ref:`merge-checklist`)
+
+* Update VERSION file to first release candidate. Check the git history of VERSION file for a version name pattern.
+
+ * As an example at the time of writing, the version name of the first release candidate was ``1.4.0-rc1``.
+ * To update the VERSION file, push a patch to Gerrit, and another maintainer should review and approve.
+
+* After submitting the change to the VERSION file, tag this commit.
+ You can check `flashrom tags in Gerrit <https://review.coreboot.org/admin/repos/flashrom,tags,25>`_
+ for tag name pattern. As an example at the time of writing, the tag name was ``v1.4.0-rc1``.
+
+* Write an announcement on the mailing list. Be very clear about:
+
+ * start and end date of the window, and what does it mean
+ * any help with :ref:`building-and-testing` is very much appreciated
+
+**From this moment and until the release cut, the highest priority is for building and testing on various environments, and bug-fixing.**
+
+Release candidates
+==================
+
+If any bugs are found and fixed (or reverted), then the second, or third release candidate will be needed.
+The process is the same as with the first candidate:
+
+* Update the VERSION file, and submit this
+* Tag the commit which updates the VERSION file
+* Post an announcement on mailing list
+
+Release notes
+=============
+
+During the time in-between releases, ideally most updates are accumulated in the doc :doc:`/release_notes/devel`.
+While this doc is helpful, it is not a replacement for a human to go through all development history
+since the previous release and prepare release notes. One maintainer is preparing the release notes
+and sending them for review, and at least one other maintainer needs to review that (it can be more than one reviewer).
+
+Ideally the patch with release notes should be prepared, reviewed and approved before the release cut,
+so that it can be published by the time of final release announcement.
+
+For inspiration to write release notes, have a look at prior art :doc:`/release_notes/index`.
+
+There is one section in release notes, Download, which is not possible to complete before the actual release cut.
+Leave it as TODO, but complete the rest.
+
+Cut the release
+===============
+
+Wait for at least a week (or two) since the last release candidate. if everything is alright:
+
+* Submit the release notes, and in the same patch restart :doc:`/release_notes/devel` document.
+ This way everyone who is syncing the repository by the release tag will have release notes in the tree.
+
+* Update VERSION file to release version (for example, at the time of writing ``1.4.0``), and submit this
+
+* Tag the commit which updates the VERSION file. You can check
+ `flashrom tags in Gerrit <https://review.coreboot.org/admin/repos/flashrom,tags,25>`_ for tag name pattern.
+ As an example at the time of writing, the tag name was ``v1.4.0``.
+
+* Create the tarball, sign it, and upload to the server together with the signature.
+
+* Update release notes with the link to download tarball, signature, and fingerprint. Submit this and check that final release notes are published on the website.
+
+* Write the release announcement, don't forget to:
+
+ * Link to download the tarball, signature and fingerprint.
+ * Say thank you to everyone who is helping and supporting flashrom
+ * Add link to published release notes on the website
+
+Start the next cycle of development
+===================================
+
+* Update the VERSION file to the development version. For example, at the time of writing ``1.5.0-devel``, and submit this.
+
+* Submit all the patches that have been ready and waiting.
+
+* Celebrate :)
diff --git a/doc/how_to_support_flashrom.rst b/doc/how_to_support_flashrom.rst
index 372ef38..7fdfdf8 100644
--- a/doc/how_to_support_flashrom.rst
+++ b/doc/how_to_support_flashrom.rst
@@ -63,6 +63,8 @@
You can check pending patches under review `in Gerrit <https://review.coreboot.org/q/status:open+project:flashrom>`_
and help with code review if a patch looks useful, you understand what it is about, and want to have it submitted.
+.. _building-and-testing:
+
Building and testing
====================
--
To view, visit https://review.coreboot.org/c/flashrom/+/83762?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: newchange
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Id6aacf5ef3879a5e236759e7a4a6af3cf7cc0a00
Gerrit-Change-Number: 83762
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Attention is currently required from: Peter Marheine.
Anastasia Klimchuk has posted comments on this change by Anastasia Klimchuk. ( https://review.coreboot.org/c/flashrom/+/83761?usp=email )
Change subject: doc: Fix the link to In-System programming doc
......................................................................
Patch Set 1:
(1 comment)
Patchset:
PS1:
I messed up the link :(
--
To view, visit https://review.coreboot.org/c/flashrom/+/83761?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Ic82be2b926b0d3a9de7d4b030bbef31c1b3746fb
Gerrit-Change-Number: 83761
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Peter Marheine <pmarheine(a)chromium.org>
Gerrit-Attention: Peter Marheine <pmarheine(a)chromium.org>
Gerrit-Comment-Date: Sat, 03 Aug 2024 13:49:17 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/83761?usp=email )
Change subject: doc: Fix the link to In-System programming doc
......................................................................
doc: Fix the link to In-System programming doc
Change-Id: Ic82be2b926b0d3a9de7d4b030bbef31c1b3746fb
Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org>
---
M doc/user_docs/overview.rst
1 file changed, 1 insertion(+), 1 deletion(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/61/83761/1
diff --git a/doc/user_docs/overview.rst b/doc/user_docs/overview.rst
index 1b3fe40..9825f22 100644
--- a/doc/user_docs/overview.rst
+++ b/doc/user_docs/overview.rst
@@ -185,7 +185,7 @@
Similarly to the DIP8 chips, these always use the SPI protocol.
However, SO8/SOIC8 chips are most often soldered onto the board directly without a socket.
-In that case a few boards have a header to allow :doc:`in-system`. You can also desolder
+In that case a few boards have a header to allow :doc:`in_system`. You can also desolder
a soldered SO8 chip and solder an SO8 socket/adapter in its place, or build
a `SOIC-to-DIP adapter <http://blogs.coreboot.org/blog/2013/07/16/gsoc-2013-flashrom-week-4/>`_.
Some of the cheapest SOIC ZIF sockets are made by `Wieson <https://www.wieson.com/go/en/wieson/index.php?lang=en>`_.
--
To view, visit https://review.coreboot.org/c/flashrom/+/83761?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: newchange
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: Ic82be2b926b0d3a9de7d4b030bbef31c1b3746fb
Gerrit-Change-Number: 83761
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Attention is currently required from: Bora Guvendik, DZ, Nikolai Artemiev, Stefan Reinauer, Subrata Banik.
Anastasia Klimchuk has posted comments on this change by Bora Guvendik. ( https://review.coreboot.org/c/flashrom/+/82626?usp=email )
Change subject: flashchips: add support for MX77U51250F chip
......................................................................
Patch Set 3:
(1 comment)
Patchset:
PS3:
Bora, I just wanted to remind that now it's your turn to action on the patch. We did the review collectively, you need to go through all unresolved comments and resolve them. Then upload the new patchset, reply to comments, and then reviewers can look at the patch again.
If you have any questions, you are welcome to ask.
Thank you!
--
To view, visit https://review.coreboot.org/c/flashrom/+/82626?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: comment
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: I2c2e94f01dc63f60cf636bc6afe1f033e2a6f83c
Gerrit-Change-Number: 82626
Gerrit-PatchSet: 3
Gerrit-Owner: Bora Guvendik <bora.guvendik(a)intel.com>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: DZ <danielzhang(a)mxic.com.cn>
Gerrit-Reviewer: Nikolai Artemiev <nartemiev(a)google.com>
Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-CC: Subrata Banik <subratabanik(a)google.com>
Gerrit-Attention: Bora Guvendik <bora.guvendik(a)intel.com>
Gerrit-Attention: DZ <danielzhang(a)mxic.com.cn>
Gerrit-Attention: Subrata Banik <subratabanik(a)google.com>
Gerrit-Attention: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Attention: Nikolai Artemiev <nartemiev(a)google.com>
Gerrit-Comment-Date: Sat, 03 Aug 2024 09:51:53 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/83584?usp=email )
Change subject: doc: Add overview doc for user_docs
......................................................................
doc: Add overview doc for user_docs
This document is converted from Technology page on wiki
https://wiki.flashrom.org/Technology
Change-Id: I93107d6b5530c301dd90f7177758632d9d1810eb
Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/83584
Reviewed-by: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org>
---
M doc/intro.rst
A doc/user_docs/Amd_am29f010_tsop32.jpg
A doc/user_docs/Bios_savior.jpg
A doc/user_docs/Dip32_chip.jpg
A doc/user_docs/Dip32_chip_back.jpg
A doc/user_docs/Dip32_in_socket.jpg
A doc/user_docs/Dip8_chip.jpg
A doc/user_docs/Dip8_chip_back.jpg
A doc/user_docs/Dip8_in_socket.jpg
A doc/user_docs/Dip_tool.jpg
A doc/user_docs/Dual_plcc32_soldered.jpg
A doc/user_docs/Empty_dip32_socket.jpg
A doc/user_docs/Empty_dip8_socket.jpg
A doc/user_docs/Empty_plcc32_socket.jpg
A doc/user_docs/Flash-BGA.jpg
A doc/user_docs/Plcc32_chip.jpg
A doc/user_docs/Plcc32_chip_back.jpg
A doc/user_docs/Plcc32_in_socket.jpg
A doc/user_docs/Plcc_tool.jpg
A doc/user_docs/Pushpin_roms_2.jpg
A doc/user_docs/Soic8_chip.jpg
A doc/user_docs/Soic8_socket_back.jpg
A doc/user_docs/Soic8_socket_front_closed.jpg
A doc/user_docs/Soic8_socket_half_opened.jpg
A doc/user_docs/Soic8_socket_open.jpg
A doc/user_docs/Soic8_socket_with_chip.jpg
A doc/user_docs/Soic8_socket_with_chip_inserted.jpg
A doc/user_docs/Soldered_plcc32.jpg
A doc/user_docs/Soldered_tsop40.jpg
A doc/user_docs/Soldered_tsop48.jpg
A doc/user_docs/Spi-socket-dscn2913-1024x768.jpg
A doc/user_docs/Sst_39vf040_tsop32.jpg
A doc/user_docs/Top_hat_flash.jpeg
M doc/user_docs/index.rst
A doc/user_docs/overview.rst
35 files changed, 303 insertions(+), 1 deletion(-)
Approvals:
Stefan Reinauer: Looks good to me, approved
build bot (Jenkins): Verified
diff --git a/doc/intro.rst b/doc/intro.rst
index b9a2c97..92bcac5 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -7,7 +7,7 @@
For more information, see the pages under :doc:`/supported_hw/index`.
* Supports parallel, LPC, FWH and SPI flash interfaces and various chip packages (DIP32,
- PLCC32, DIP8, SO8/SOIC8, TSOP32, TSOP40, TSOP48, BGA and more).
+ PLCC32, DIP8, SO8/SOIC8, TSOP32, TSOP40, TSOP48, BGA and more), see :doc:`user_docs/overview`.
* No physical access needed, root access is sufficient (not needed for some programmers).
diff --git a/doc/user_docs/Amd_am29f010_tsop32.jpg b/doc/user_docs/Amd_am29f010_tsop32.jpg
new file mode 100644
index 0000000..faf0982
--- /dev/null
+++ b/doc/user_docs/Amd_am29f010_tsop32.jpg
Binary files differ
diff --git a/doc/user_docs/Bios_savior.jpg b/doc/user_docs/Bios_savior.jpg
new file mode 100644
index 0000000..91d5557
--- /dev/null
+++ b/doc/user_docs/Bios_savior.jpg
Binary files differ
diff --git a/doc/user_docs/Dip32_chip.jpg b/doc/user_docs/Dip32_chip.jpg
new file mode 100644
index 0000000..5eede28
--- /dev/null
+++ b/doc/user_docs/Dip32_chip.jpg
Binary files differ
diff --git a/doc/user_docs/Dip32_chip_back.jpg b/doc/user_docs/Dip32_chip_back.jpg
new file mode 100644
index 0000000..f564505
--- /dev/null
+++ b/doc/user_docs/Dip32_chip_back.jpg
Binary files differ
diff --git a/doc/user_docs/Dip32_in_socket.jpg b/doc/user_docs/Dip32_in_socket.jpg
new file mode 100644
index 0000000..38467a3
--- /dev/null
+++ b/doc/user_docs/Dip32_in_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Dip8_chip.jpg b/doc/user_docs/Dip8_chip.jpg
new file mode 100644
index 0000000..b1afb41
--- /dev/null
+++ b/doc/user_docs/Dip8_chip.jpg
Binary files differ
diff --git a/doc/user_docs/Dip8_chip_back.jpg b/doc/user_docs/Dip8_chip_back.jpg
new file mode 100644
index 0000000..768e17a
--- /dev/null
+++ b/doc/user_docs/Dip8_chip_back.jpg
Binary files differ
diff --git a/doc/user_docs/Dip8_in_socket.jpg b/doc/user_docs/Dip8_in_socket.jpg
new file mode 100644
index 0000000..0450cbc
--- /dev/null
+++ b/doc/user_docs/Dip8_in_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Dip_tool.jpg b/doc/user_docs/Dip_tool.jpg
new file mode 100644
index 0000000..6063333
--- /dev/null
+++ b/doc/user_docs/Dip_tool.jpg
Binary files differ
diff --git a/doc/user_docs/Dual_plcc32_soldered.jpg b/doc/user_docs/Dual_plcc32_soldered.jpg
new file mode 100644
index 0000000..7d74251
--- /dev/null
+++ b/doc/user_docs/Dual_plcc32_soldered.jpg
Binary files differ
diff --git a/doc/user_docs/Empty_dip32_socket.jpg b/doc/user_docs/Empty_dip32_socket.jpg
new file mode 100644
index 0000000..0c44c3a
--- /dev/null
+++ b/doc/user_docs/Empty_dip32_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Empty_dip8_socket.jpg b/doc/user_docs/Empty_dip8_socket.jpg
new file mode 100644
index 0000000..22e843b
--- /dev/null
+++ b/doc/user_docs/Empty_dip8_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Empty_plcc32_socket.jpg b/doc/user_docs/Empty_plcc32_socket.jpg
new file mode 100644
index 0000000..acd20b1
--- /dev/null
+++ b/doc/user_docs/Empty_plcc32_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Flash-BGA.jpg b/doc/user_docs/Flash-BGA.jpg
new file mode 100644
index 0000000..2eb059b
--- /dev/null
+++ b/doc/user_docs/Flash-BGA.jpg
Binary files differ
diff --git a/doc/user_docs/Plcc32_chip.jpg b/doc/user_docs/Plcc32_chip.jpg
new file mode 100644
index 0000000..3a0193a
--- /dev/null
+++ b/doc/user_docs/Plcc32_chip.jpg
Binary files differ
diff --git a/doc/user_docs/Plcc32_chip_back.jpg b/doc/user_docs/Plcc32_chip_back.jpg
new file mode 100644
index 0000000..f016900
--- /dev/null
+++ b/doc/user_docs/Plcc32_chip_back.jpg
Binary files differ
diff --git a/doc/user_docs/Plcc32_in_socket.jpg b/doc/user_docs/Plcc32_in_socket.jpg
new file mode 100644
index 0000000..241794c
--- /dev/null
+++ b/doc/user_docs/Plcc32_in_socket.jpg
Binary files differ
diff --git a/doc/user_docs/Plcc_tool.jpg b/doc/user_docs/Plcc_tool.jpg
new file mode 100644
index 0000000..3d3b801
--- /dev/null
+++ b/doc/user_docs/Plcc_tool.jpg
Binary files differ
diff --git a/doc/user_docs/Pushpin_roms_2.jpg b/doc/user_docs/Pushpin_roms_2.jpg
new file mode 100644
index 0000000..c4ce5ae
--- /dev/null
+++ b/doc/user_docs/Pushpin_roms_2.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_chip.jpg b/doc/user_docs/Soic8_chip.jpg
new file mode 100644
index 0000000..d103c7d
--- /dev/null
+++ b/doc/user_docs/Soic8_chip.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_back.jpg b/doc/user_docs/Soic8_socket_back.jpg
new file mode 100644
index 0000000..49504e2
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_back.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_front_closed.jpg b/doc/user_docs/Soic8_socket_front_closed.jpg
new file mode 100644
index 0000000..f6aebd5
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_front_closed.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_half_opened.jpg b/doc/user_docs/Soic8_socket_half_opened.jpg
new file mode 100644
index 0000000..f4d5730
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_half_opened.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_open.jpg b/doc/user_docs/Soic8_socket_open.jpg
new file mode 100644
index 0000000..69b4e74
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_open.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_with_chip.jpg b/doc/user_docs/Soic8_socket_with_chip.jpg
new file mode 100644
index 0000000..322f638
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_with_chip.jpg
Binary files differ
diff --git a/doc/user_docs/Soic8_socket_with_chip_inserted.jpg b/doc/user_docs/Soic8_socket_with_chip_inserted.jpg
new file mode 100644
index 0000000..37af90d
--- /dev/null
+++ b/doc/user_docs/Soic8_socket_with_chip_inserted.jpg
Binary files differ
diff --git a/doc/user_docs/Soldered_plcc32.jpg b/doc/user_docs/Soldered_plcc32.jpg
new file mode 100644
index 0000000..8a3a6cd
--- /dev/null
+++ b/doc/user_docs/Soldered_plcc32.jpg
Binary files differ
diff --git a/doc/user_docs/Soldered_tsop40.jpg b/doc/user_docs/Soldered_tsop40.jpg
new file mode 100644
index 0000000..1fcf2ef
--- /dev/null
+++ b/doc/user_docs/Soldered_tsop40.jpg
Binary files differ
diff --git a/doc/user_docs/Soldered_tsop48.jpg b/doc/user_docs/Soldered_tsop48.jpg
new file mode 100644
index 0000000..3df63ee
--- /dev/null
+++ b/doc/user_docs/Soldered_tsop48.jpg
Binary files differ
diff --git a/doc/user_docs/Spi-socket-dscn2913-1024x768.jpg b/doc/user_docs/Spi-socket-dscn2913-1024x768.jpg
new file mode 100644
index 0000000..3b20ae0
--- /dev/null
+++ b/doc/user_docs/Spi-socket-dscn2913-1024x768.jpg
Binary files differ
diff --git a/doc/user_docs/Sst_39vf040_tsop32.jpg b/doc/user_docs/Sst_39vf040_tsop32.jpg
new file mode 100644
index 0000000..beefeba
--- /dev/null
+++ b/doc/user_docs/Sst_39vf040_tsop32.jpg
Binary files differ
diff --git a/doc/user_docs/Top_hat_flash.jpeg b/doc/user_docs/Top_hat_flash.jpeg
new file mode 100644
index 0000000..8edd27e
--- /dev/null
+++ b/doc/user_docs/Top_hat_flash.jpeg
Binary files differ
diff --git a/doc/user_docs/index.rst b/doc/user_docs/index.rst
index 3ca928a..6eadfa4 100644
--- a/doc/user_docs/index.rst
+++ b/doc/user_docs/index.rst
@@ -4,6 +4,7 @@
.. toctree::
:maxdepth: 1
+ overview
fw_updates_vs_spi_wp
example_partial_wp
chromebooks
diff --git a/doc/user_docs/overview.rst b/doc/user_docs/overview.rst
new file mode 100644
index 0000000..1b3fe40
--- /dev/null
+++ b/doc/user_docs/overview.rst
@@ -0,0 +1,301 @@
+==========
+Overview
+==========
+
+Modern mainboards store the BIOS in a reprogrammable flash chip.
+There are hundreds of different flash (`EEPROM <https://en.wikipedia.org/wiki/EEPROM>`_) chips,
+with variables such as memory size, speed, communication bus (Parallel, LPC, FWH, SPI) and packaging to name just a few.
+
+Packaging/housing/form factor
+=============================
+
+DIP32: Dual In-line Package, 32 pins
+------------------------------------
+
+DIP32 top
+
+.. image:: Dip32_chip.jpg
+ :alt: DIP32 top
+
+DIP32 bottom
+
+.. image:: Dip32_chip_back.jpg
+ :alt: DIP32 bottom
+
+DIP32 in a socket
+
+.. image:: Dip32_in_socket.jpg
+ :alt: DIP32 in a socket
+
+DIP32 socket
+
+.. image:: Empty_dip32_socket.jpg
+ :alt: DIP32 socket
+
+DIP32 extractor tool
+
+.. image:: Dip_tool.jpg
+ :alt: DIP32 extractor tool
+
+A rectangular black plastic block with 16 pins along each of the two longer sides of the package
+(32 pins in total). DIP32 chips can be socketed which means they are detachable from the mainboard
+using physical force. If they haven't been moved in and out of the socket very much,
+they can appear to be quite difficult to release from the socket. One way to remove a DIP32 chip
+from a socket is by prying a **thin screwdriver** in between the plastic package and the socket,
+along the shorter sides where there are no pins, and then gently bending the screwdriver to push
+the chip upwards, away from the mainboard. Alternate between the two sides to avoid bending the pins,
+and don't touch any of the pins with the screwdriver (search about ESD, electro-static discharge).
+If the chip is **soldered directly to the mainboard**, it has to be desoldered in order to be
+reprogrammed outside the mainboard. If you do this, it's a good idea to
+`solder a socket to the mainboard <http://www.coreboot.org/Soldering_a_socket_on_your_board>`_ instead,
+to ease any future experiments.
+
+PLCC32: Plastic Leaded Chip Carrier, 32 pins
+--------------------------------------------
+
+PLCC32 top
+
+ .. image:: Plcc32_chip.jpg
+ :alt: PLCC32 top
+
+PLCC32 botto
+
+ .. image:: Plcc32_chip_back.jpg
+ :alt: PLCC32 bottom
+
+PLCC32 socket
+
+ .. image:: Plcc32_in_socket.jpg
+ :alt: PLCC32 socket
+
+PLCC32 in a socket
+
+ .. image:: Empty_plcc32_socket.jpg
+ :alt: PLCC32 in a socket
+
+Soldered PLCC3
+
+ .. image:: Soldered_plcc32.jpg
+ :alt: Soldered PLCC32
+
+Two soldered PLCC32
+
+ .. image:: Dual_plcc32_soldered.jpg
+ :alt: Two soldered PLCC32
+
+PLCC32 Bios Savior
+
+ .. image:: Bios_savior.jpg
+ :alt: PLCC32 Bios Savior
+
+PLCC32 Top-Hat-Flash adapte
+
+ .. image:: Top_hat_flash.jpeg
+ :alt: PLCC32 Top-Hat-Flash adapter
+
+PLCC32 pushpin trick
+
+ .. image:: Pushpin_roms_2.jpg
+ :alt: PLCC32 pushpin trick
+
+PLCC extractor tool
+
+ .. image:: Plcc_tool.jpg
+ :alt: PLCC extractor tool
+
+Black plastic block again, but this one is much more square.
+PLCC32 was becoming the standard for mainboards after DIP32 chips because of its smaller physical size.
+PLCC can also be **socketed** or **soldered directly to the mainboard**.
+Socketed PLCC32 chips can be removed using a special PLCC removal tool,
+or using a piece of nylon line tied in a loop around the chip and pulled swiftly straight up,
+or bending/prying using small screwdrivers if one is careful. PLCC32 sockets are often fragile
+so the screwdriver approach is not recommended. While the nylon line method sounds strange it works well.
+Desoldering PLCC32 chips and soldering on a socket can be done using either a desoldering station
+or even just a heat gun. You can also cut the chip with a sharp knife, **but it will be destroyed in the process, of course**.
+
+DIP8: Dual In-line Package, 8 pins
+----------------------------------
+
+DIP8 top
+
+ .. image:: Dip8_chip.jpg
+ :alt: DIP8 top
+
+DIP8 bottom
+
+ .. image:: Dip8_chip_back.jpg
+ :alt: DIP8 bottom
+
+DIP8 in a socket
+
+ .. image:: Dip8_in_socket.jpg
+ :alt: DIP8 in a socket
+
+DIP8 socket
+
+ .. image:: Empty_dip8_socket.jpg
+ :alt: DIP8 socket
+
+Most recent boards use DIP8 chips (which always employ the SPI protocol) or SO8/SOIC8 chips (see below).
+DIP8 chips are always **socketed**, and can thus be easily removed (and hot-swapped),
+for example using a small screwdriver. This allows for relatively simple recovery in case of an incorrectly flashed chip.
+
+SO8/SOIC8: Small-Outline Integrated Circuit, 8 pins
+---------------------------------------------------
+
+Soldered SOIC8
+
+ .. image:: Soic8_chip.jpg
+ :alt: Soldered SOIC8
+
+SOIC8 socket, front, closed
+
+ .. image:: Soic8_socket_front_closed.jpg
+ :alt: SOIC8 socket, front, closed
+
+SOIC8 socket, half open
+
+ .. image:: Soic8_socket_half_opened.jpg
+ :alt: SOIC8 socket, half open
+
+SOIC8 socket, open
+
+ .. image:: Soic8_socket_open.jpg
+ :alt: SOIC8 socket, open
+
+SOIC8 socket, back
+
+ .. image:: Soic8_socket_back.jpg
+ :alt: SOIC8 socket, back
+
+SOIC8 socket, chip nearby
+
+ .. image:: Soic8_socket_with_chip.jpg
+ :alt: SOIC8 socket, chip nearby
+
+SOIC8 socket, chip inserted
+
+ .. image:: Soic8_socket_with_chip_inserted.jpg
+ :alt: SOIC8 socket, chip inserted
+
+Another type of SOIC8 adapter
+
+ .. image:: Spi-socket-dscn2913-1024x768.jpg
+ :alt: Another type of SOIC8 adapter
+
+Similarly to the DIP8 chips, these always use the SPI protocol.
+However, SO8/SOIC8 chips are most often soldered onto the board directly without a socket.
+In that case a few boards have a header to allow :doc:`in-system`. You can also desolder
+a soldered SO8 chip and solder an SO8 socket/adapter in its place, or build
+a `SOIC-to-DIP adapter <http://blogs.coreboot.org/blog/2013/07/16/gsoc-2013-flashrom-week-4/>`_.
+Some of the cheapest SOIC ZIF sockets are made by `Wieson <https://www.wieson.com/go/en/wieson/index.php?lang=en>`_.
+They have 3 models available - G6179-10(0000), G6179-20(0000) and a 16 pin version named G6179-07(0000).
+They are available for example from `siliconkit <https://siliconkit.com/oc3/>`_,
+`Dediprog <https://www.dediprog.com/>`_, as well as `alibaba <http://alibaba.com/>`_.
+For the usual "BIOS" flash chips you want the G6179-10 model (look also for G6179-100000).
+Dediprog usually has them or similar ones as well but has steep shipping costs and an unpractical minimum order quantity.
+
+TSOP: Thin Small-Outline Package, 32, 40, or 48 pins
+----------------------------------------------------
+
+Soldered TSOP32
+
+ .. image:: Amd_am29f010_tsop32.jpg
+ :alt: Soldered TSOP32
+
+Soldered TSOP32
+
+ .. image:: Sst_39vf040_tsop32.jpg
+ :alt: Soldered TSOP32
+
+Soldered TSOP40
+
+ .. image:: Soldered_tsop40.jpg
+ :alt: Soldered TSOP40
+
+Soldered TSOP48
+
+ .. image:: Soldered_tsop48.jpg
+ :alt: Soldered TSOP48
+
+TSOPs are often used in embedded systems where size is important and there is no need
+for replacement in the field. It is possible to (de)solder TSOPs by hand,
+but it's not trivial and a reasonable amount of soldering skills are required.
+
+BGA: Ball Grid Array
+--------------------
+
+BGA package flash
+
+ .. image:: Flash-BGA.jpg
+ :alt: BGA package flash
+
+BGAs are often used in embedded systems where size is important and there is no need
+for replacement in the field. It is not easily possible to (de)solder BGA by hand.
+
+Communication bus protocol
+==========================
+
+There are four major communication bus protocols for flash chips,
+each with multiple subtle variants in the command set:
+
+* **SPI**: Serial Peripheral Interface, introduced ca. 2006.
+* **Parallel**: The oldest flash bus, phased out on mainboards around 2002.
+* **LPC**: Low Pin Count, a standard introduced ca. 1998.
+* **FWH**: Firmware Hub, a variant of the LPC standard introduced at the same time.
+ FWH is a special case variant of LPC with one bit set differently in the memory read/write commands.
+ That means some data sheets mention the chips speak LPC although
+ they will not respond to regular LPC read/write cycles.
+
+Here's an attempt to create a marketing language -> chip type mapping:
+
+* JEDEC Flash -> Parallel (well, mostly)
+* FWH -> FWH
+* Firmware Hub -> FWH
+* LPC Firmware -> FWH
+* Firmware Memory -> FWH
+* Low Pin Count (if Firmware/FWH is not mentioned) -> LPC
+* LPC (if Firmware is not mentioned) -> LPC
+* Serial Flash -> SPI
+
+SST data sheets have the following conventions:
+
+* LPC Memory Read -> LPC
+* Firmware Memory Read -> FWH
+
+If both are mentioned, the chip supports both.
+
+If you're not sure about whether a device is LPC or FWH, look at the read/write cycle definitions.
+
+FWH
+
+=========== ========== ============== ==========================================================
+Clock Cycle Field Name Field contents Comments
+=========== ========== ============== ==========================================================
+1 START 1101/1110 1101 for READ, 1110 for WRITE.
+2 IDSEL 0000 to 1111 IDSEL value to be shifted out to the chip.
+3-9 IMADDR YYYY The address to be read/written. 7 cycles total == 28 bits.
+10+ ... ... ...
+=========== ========== ============== ==========================================================
+
+LPC
+
+=========== =================== ============== ==========================================================
+Clock Cycle Field Name Field contents Comments
+=========== =================== ============== ==========================================================
+1 START 0000 ...
+2 CYCLETYPE+DIRECTION 010X/011X 010X for READ, 011X for WRITE. X means "reserved".
+3-10 ADDRESS YYYY The address to be read/written. 8 cycles total == 32 bits.
+11+ ... ... ...
+=========== =================== ============== ==========================================================
+
+Generally, a parallel flash chip will not speak any other protocols.
+SPI flash chips also don't speak any other protocols.
+LPC flash chips sometimes speak FWH as well and vice versa,
+but they will not speak any protocols besides LPC/FWH.
+
+Hardware Redundancy
+===================
+Gigabyte's DualBios: http://www.google.com/patents/US6892323
+
+ASUS: http://www.google.com/patents/US8015449
--
To view, visit https://review.coreboot.org/c/flashrom/+/83584?usp=email
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings?usp=email
Gerrit-MessageType: merged
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: I93107d6b5530c301dd90f7177758632d9d1810eb
Gerrit-Change-Number: 83584
Gerrit-PatchSet: 3
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>