Anastasia Klimchuk has uploaded this change for review.
doc: Add page with misc notes and advice
This page is a combination of info from the following pages:
https://wiki.flashrom.org/Common_problems
https://wiki.flashrom.org/Connections
https://wiki.flashrom.org/FAQ
https://wiki.flashrom.org/Random_notes
https://wiki.flashrom.org/Live_CD
Change-Id: I538f31765576584760524cd8b06cbf5bce191bde
Signed-off-by: Anastasia Klimchuk <aklm@flashrom.org>
---
M doc/user_docs/index.rst
A doc/user_docs/misc_notes.rst
2 files changed, 150 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/50/83450/1
diff --git a/doc/user_docs/index.rst b/doc/user_docs/index.rst
index b61567a..960659e 100644
--- a/doc/user_docs/index.rst
+++ b/doc/user_docs/index.rst
@@ -9,3 +9,4 @@
chromebooks
management_engine
misc_intel
+ misc_notes
diff --git a/doc/user_docs/misc_notes.rst b/doc/user_docs/misc_notes.rst
new file mode 100644
index 0000000..fcb1700
--- /dev/null
+++ b/doc/user_docs/misc_notes.rst
@@ -0,0 +1,149 @@
+=====================
+Misc notes and advice
+=====================
+
+This document contains miscellaneous and unstructured (and mostly, legacy) notes and advice about using flashrom.
+
+Command set tricks for parallel and LPC chips
+=============================================
+
+This is only mentioned in very few datasheets, but it applies to some parallel (and some LPC) chips.
+
+Upper address bits of commands are ignored if they are not mentioned explicitly. If a datasheet specifies the following sequence::
+
+ chip_writeb(0xAA, bios + 0x555);
+ chip_writeb(0x55, bios + 0x2AA);
+ chip_writeb(0x90, bios + 0x555);
+
+then it is quite likely the following sequence will work as well::
+
+ chip_writeb(0xAA, bios + 0x5555);
+ chip_writeb(0x55, bios + 0x2AAA);
+ chip_writeb(0x90, bios + 0x5555);
+
+However, if the chip datasheet specifies addresses like ``0x5555``, you can't shorten them to ``0x555``.
+
+To summarize, replacing short addresses with long addresses usually works, but the other way round usually fails.
+
+flashrom doesn't work on my board, what can I do?
+=================================================
+
+* First of all, check if your chipset, ROM chip, and mainboard are supported
+ (see :doc:`/supported_hw/index`).
+* If your board has a jumper for BIOS flash protection (check the manual), disable it.
+* Should your BIOS menu have a BIOS flash protection option, disable it.
+* If you run flashrom on Linux and see messages about ``/dev/mem``, see next section.
+* If you run flashrom on OpenBSD, you might need to obtain raw access permission by setting
+ ``securelevel = -1`` in ``/etc/rc.securelevel`` and rebooting, or rebooting into single user mode.
+
+What can I do about /dev/mem errors?
+====================================
+
+* If flashrom tells you ``/dev/mem mmap failed: Operation not permitted``:
+
+ * Most common at the time of writing is a Linux kernel option, ``CONFIG_IO_STRICT_DEVMEM``,
+ that prevents even the root user from accessing hardware from user-space if the resource is unknown
+ to the kernel or a conflicting kernel driver reserved it. On Intel systems, this is most often ``lpc_ich``,
+ so ``modprobe -r lpc_ich`` can help. A more invasive solution is to try again after rebooting
+ with ``iomem=relaxed`` in the kernel command line.
+
+ * Some systems with incorrect memory reservations (e.g. E820 map) may have the same problem
+ even with ``CONFIG_STRICT_DEVMEM``. In that case ``iomem=relaxed`` in the kernel command line may help too.
+
+* If it tells you ``/dev/mem mmap failed: Resource temporarily unavailable``:
+
+ * This may be an issue with PAT (e.g. if the memory flashrom tries to map is already mapped
+ in an incompatible mode). Try again after rebooting with nopat in the kernel command line.
+
+* If you see this message ``Can't mmap memory using /dev/mem: Invalid argument``:
+
+ * Your flashrom is very old, better update it. If the issue persists, try the kernel options mentioned above.
+
+* Generally, if your version of flashrom is very old, an update might help.
+ Flashrom has less strict requirements now and works on more systems without having to change the kernel.
+
+Connections
+===========
+
+Using In-System programming requires some means to connect the external programmer to the flash chip.
+
+Note that some external flashers (like the Openmoko debug board) lack a connector,
+so they do requires some soldering to be used. Some other don't. For instance the buspirate has a pin connector on it.
+
+Programmer <-> Removable chip connection
+----------------------------------------
+
+A breadboard can be used to connect Dual in-line 8 pins chips to the programmer, as they they fit well into it.
+
+Programmer <-> Clip connection
+------------------------------
+
+If your programmer has a pin connector, and that you want to avoid soldering, you can use
+**Short** `Jump Wires <https://en.wikipedia.org/wiki/Jump_wire>`_ to connect it to a clip.
+They usually can be found on some electronic shops.
+
+Other issues
+-------------
+
+* Wires length and connection quality: Long wires, and bad connection can create some issues, so avoid them.
+
+ * The maximum wires length is very dependent on your setup, so try to have the shortest wires possible.
+ * If you can't avoid long wires and if you're flash chip is SPI, then lowering the SPI clock could make
+ it work in some cases. Many programmers do support such option (Called spispeed with most of them, or divisor with ft2232_spi).
+
+* When soldering wires, the wire tend to break near the soldering point. To avoid such issue,
+ you have to prevent the wires from bending near the soldering point.
+ To do that `Heat-shrink_tubing <https://en.wikipedia.org/wiki/Heat-shrink_tubing>`_ or similar methods can be used.
+
+Common problems
+===============
+
+The following describes problems commonly found when trying to access flash chips in systems
+that are not designed properly for this job, e.g. ad-hoc setups to flash in-system
+(TODO add a doc for in-system-specific problems).
+
+Symptoms indicating you may have at least one of these are for example inconsistent reads or probing results.
+This happens basically because the analog electrical waveforms representing the digital information
+get too distorted to by interpreted correctly all the time. Depending on the cause different steps can be tried.
+
+* Not all input pins are connected to the correct voltage level/output pin of the programmer.
+ Always connect all input pins of ICs!
+
+* The easiest thing to try is lowering the (SPI) clock frequency if your programmer supports it.
+ That way the waveforms have more time to settle before being sampled by the receiver which might be enough.
+ Depending on the design of the driver and receiver as well as the actual communication path
+ this might not change anything as well.
+
+* Wires are too long. Shortening them to a few cm (i.e. < 20, the lesser the better) might help.
+
+* The impedances of the wires/traces do not match the impedances of the input pins
+ (of either the circuit/chip on the mainboard or the external programmer).
+ Try using shorter wires, adding small (<100 Ohm) series resistors or parallel capacitors (<20pF)
+ as near as possible to the input pins (this includes also the MISO line which ends near the programmer)\
+ and/or ask someone who has experience with high frequency electronics.
+
+* The supply voltage of the flash chip is not stable enough. Try adding a 0.1 µF - 1 µF (ceramic) capacitor
+ between the flash chip's VCC and GND pins as near as possible to the chip.
+
+Live CD
+=========
+
+A Live CD containing flashrom provides a user with a stable work environment to read, write and verify a flash device on any supported hardware.
+
+It can help avoid Linux installation issues, which can be a hassle for some users.
+
+flashrom is already shipped in some of the Live CDs, see below. *Please note, some of these ship very old versions of flashrom*.
+
+* `SystemRescueCd <http://www.sysresccd.org/>`_ has been including flashrom since about version 2.5.1.
+
+* `grml <http://grml.org/>`_
+
+ * Note: You need the full grml ISO, "small" (and "medium") ISOs do not contain flashrom.
+ * Note: Some releases (e.g. 2011.12) did not contain flashrom.
+
+* `Parted Magic <http://partedmagic.com/>`_
+
+* `Hiren's BootCD <http://www.hirensbootcd.org/>`_
+
+ * When you select "Linux based rescue environment (Parted Magic 6.7)" and then "Live with default settings",
+ you have access to a system which has flashrom.
To view, visit change 83450. To unsubscribe, or for help writing mail filters, visit settings.