Anastasia Klimchuk has uploaded this change for review.

View Change

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@flashrom.org>
---
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
34 files changed, 302 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/flashrom refs/changes/84/83584/1
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 b61567a..4be71bb 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 change 83584. To unsubscribe, or for help writing mail filters, visit settings.

Gerrit-MessageType: newchange
Gerrit-Project: flashrom
Gerrit-Branch: main
Gerrit-Change-Id: I93107d6b5530c301dd90f7177758632d9d1810eb
Gerrit-Change-Number: 83584
Gerrit-PatchSet: 1
Gerrit-Owner: Anastasia Klimchuk <aklm@chromium.org>