Anastasia Klimchuk has uploaded this change for review.
doc: Convert serprog docs to rst and add to doc directory
Change-Id: Ie52f1e051ed215d61d5fb535e3eddeac71f64d13
Signed-off-by: Anastasia Klimchuk <aklm@flashrom.org>
---
D Documentation/serprog-protocol.txt
M doc/classic_cli_manpage.rst
M doc/index.rst
A doc/supported_hw/index.rst
A doc/supported_hw/supported_prog/index.rst
A doc/supported_hw/supported_prog/serprog/166px-Serprogduino_v2.jpeg
A doc/supported_hw/supported_prog/serprog/250px-Arduino_5V_lpc_spi_shield.jpg
A doc/supported_hw/supported_prog/serprog/250px-Arduino_lpcspi_shield_render.png
A doc/supported_hw/supported_prog/serprog/300px-AtmegaXXu2-flasher.jpg
A doc/supported_hw/supported_prog/serprog/300px-Avr_rs232_programmer.jpg
A doc/supported_hw/supported_prog/serprog/300px-HydraFW_Default_PinAssignment.png
A doc/supported_hw/supported_prog/serprog/300px-Serprog-stm32vcp.jpg
A doc/supported_hw/supported_prog/serprog/300px-Serprog_0001.jpeg
A doc/supported_hw/supported_prog/serprog/300px-Teensy31_lpcspi_flasher.jpg
A doc/supported_hw/supported_prog/serprog/P1v1_arduino328.png
A doc/supported_hw/supported_prog/serprog/P1v2_arduino1280.png
A doc/supported_hw/supported_prog/serprog/P2v1_resdivider.png
A doc/supported_hw/supported_prog/serprog/P2v2_oc_cs.png
A doc/supported_hw/supported_prog/serprog/P2v3_buffer4050.png
A doc/supported_hw/supported_prog/serprog/P3v1_dil8_so8_spi.png
A doc/supported_hw/supported_prog/serprog/P3v2_so16_spi.png
A doc/supported_hw/supported_prog/serprog/arduino_flasher.rst
A doc/supported_hw/supported_prog/serprog/arduino_flasher_3.3v.rst
A doc/supported_hw/supported_prog/serprog/index.rst
A doc/supported_hw/supported_prog/serprog/overview.rst
A doc/supported_hw/supported_prog/serprog/serprog-protocol.rst
A doc/supported_hw/supported_prog/serprog/teensy_3_1.rst
27 files changed, 808 insertions(+), 124 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/18/82018/1
diff --git a/Documentation/serprog-protocol.txt b/Documentation/serprog-protocol.txt
deleted file mode 100644
index d001ceb..0000000
--- a/Documentation/serprog-protocol.txt
+++ /dev/null
@@ -1,123 +0,0 @@
-Serial Flasher Protocol Specification - version 1 (0x01 return value == 1)
-
-Command And Answer Sequence - all commands give an answer.
-PC: COMMAND(8bit) <parameters determined by opcode>
-DEV: ACK/NAK(8bit) <OPTIONAL RETURN BYTES (only if ACK)> / nothing
-Command 0x10 (SYNCNOP) has a special return of NAK+ACK for synchronization.
-
-ACK = 0x06
-NAK = 0x15
-
-All multibyte values are little-endian. Addresses and lengths are 24-bit.
-
-COMMAND Description Parameters Return Value
-0x00 NOP none ACK
-0x01 Query programmer iface version none ACK + 16bit version (nonzero)
-0x02 Query supported commands bitmap none ACK + 32 bytes (256 bits) of supported cmds flags
-0x03 Query programmer name none ACK + 16 bytes string (null padding) / NAK
-0x04 Query serial buffer size none ACK + 16bit size / NAK
-0x05 Query supported bustypes none ACK + 8-bit flags (as per flashrom) / NAK
-0x06 Query connected address lines none ACK + 8bit line count / NAK
-0x07 Query operation buffer size none ACK + 16bit size / NAK
-0x08 Query maximum write-n length none ACK + 24bit length (0==2^24) / NAK
-0x09 Read byte 24-bit addr ACK + BYTE / NAK
-0x0A Read n bytes 24-bit addr + 24-bit length ACK + length bytes / NAK
-0x0B Initialize operation buffer none ACK / NAK
-0x0C Write to opbuf: Write byte 24-bit addr + 8-bit byte ACK / NAK (NOTE: takes 5 bytes in opbuf)
-0x0D Write to opbuf: Write n 24-bit length + 24-bit addr + ACK / NAK (NOTE: takes 7+n bytes in opbuf)
- + length bytes of data
-0x0E Write to opbuf: delay 32-bit usecs ACK / NAK (NOTE: takes 5 bytes in opbuf)
-0x0F Execute operation buffer none ACK / NAK
-0x10 Sync NOP none NAK + ACK (for synchronization)
-0x11 Query maximum read-n length none ACK + 24-bit length (0==2^24) / NAK
-0x12 Set used bustype 8-bit flags (as with 0x05) ACK / NAK
-0x13 Perform SPI operation 24-bit slen + 24-bit rlen ACK + rlen bytes of data / NAK
- + slen bytes of data
-0x14 Set SPI clock frequency in Hz 32-bit requested frequency ACK + 32-bit set frequency / NAK
-0x15 Toggle flash chip pin drivers 8-bit (0 disable, else enable) ACK / NAK
-0x16 Set SPI Chip Select 8-bit ACK / NAK
-0x17 Set SPI Mode 8-bit ACK / NAK
-0x18 Set CS Mode 8-bit ACK / NAK
-0x?? unimplemented command - invalid.
-
-
-Additional information of the above commands:
- About unimplemented commands / startup sequence:
- Only commands allowed to be used without checking anything are 0x00,0x10 and 0x01 (NOP,SYNCNOP,Q_IFACE).
- If 0x01 doesn't return 1, dont do anything if you dont support a newer protocol.
- Then, check support for any other opcode (except 0x02) by using 0x02 (Q_CMDMAP).
- 0x02 (Q_CMDMAP):
- The map's bits are mapped as follows:
- cmd 0 support: byte 0 bit 0
- cmd 1 support: byte 0 bit 1
- cmd 7 support: byte 0 bit 7
- cmd 8 support: byte 1 bit 0, and so on.
- 0x04 (Q_SERBUF):
- If the programmer has a guaranteed working flow control,
- it should return a big bogus value - eg 0xFFFF.
- 0x05 (Q_BUSTYPE):
- The bit's are defined as follows:
- bit 0: PARALLEL, bit 1: LPC, bit 2: FWH, bit 3: SPI.
- 0x06 (Q_CHIPSIZE):
- Only applicable to parallel programmers.
- An LPC/FWH/SPI-programmer can report this as not supported in the command bitmap.
- 0x08 (Q_WRNMAXLEN):
- If a programmer reports a bigger maximum write-n length than the serial buffer size,
- it is assumed that the programmer can process the data fast enough to take in the
- reported maximum write-n without problems.
- 0x0F (O_EXEC):
- Execute operation buffer will also clear it, regardless of the return value.
- 0x11 (Q_RDNMAXLEN):
- If this command is not supported, assume return of 0 (2^24).
- 0x12 (S_BUSTYPE):
- Set's the used bustype if the programmer can support more than one flash protocol.
- Sending a byte with more than 1 bit set will make the programmer decide among them
- on it's own. Bit values as with Q_BUSTYPE.
- 0x13 (O_SPIOP):
- Send and receive bytes via SPI.
- Maximum slen is Q_WRNMAXLEN in case Q_BUSTYPE returns SPI only or S_BUSTYPE was used
- to set SPI exclusively before. Same for rlen and Q_RDNMAXLEN.
- This operation is immediate, meaning it doesn't use the operation buffer.
- 0x14 (S_SPI_FREQ):
- Set the SPI clock frequency. The 32-bit value indicates the
- requested frequency in Hertz. Value 0 is reserved and should
- be NAKed by the programmer. The requested frequency should be
- mapped by the programmer software to a supported frequency
- lower than the one requested. If there is no lower frequency
- available the lowest possible should be used. The value
- chosen is sent back in the reply with an ACK.
- 0x15 (S_PIN_STATE):
- Sets the state of the pin drivers connected to the flash chip. Disabling them allows other
- devices (e.g. a mainboard's chipset) to access the chip. This way the serprog controller can
- remain attached to the flash chip even when the board is running. The user is responsible to
- NOT connect VCC and other permanently externally driven signals to the programmer as needed.
- If the value is 0, then the drivers should be disabled, otherwise they should be enabled.
- 0x16 (S_SPI_CS):
- Set which SPI Chip Select pin to use. This operation is immediate,
- meaning it doesn't use the operation buffer.
- 0x17 (S_SPI_MODE):
- Set which SPI Mode to use for 0x13 O_SPIOP commands.
- This operation is immediate, meaning it doesn't use the operation buffer.
- The current defined modes are:
- 0x00: SPI Half Duplex (default)
- 0x01: SPI Full Duplex
- 0x18 (S_CS_MODE):
- Set which CS Mode to use. The CS Mode determines the CS behaviour.
- This allows manual control over the CS.
- This operation is immediate, meaning it doesn't use the operation buffer.
- The current defined modes are:
- 0x00: CS Auto Mode. The CS gets selected before 0x13 O_SPIOP commands and
- deselected afterwards. (default)
- 0x01: CS Selected. The CS will be selected until another mode is set.
- 0x02: CS Deselected. The CS will be deselected until another mode is set.
- About mandatory commands:
- The only truly mandatory commands for any device are 0x00, 0x01, 0x02 and 0x10,
- but one can't really do anything with these commands.
- Support for the following commands is necessary for flashrom to operate properly:
- S_CMD_Q_SERBUF, S_CMD_Q_OPBUF, S_CMD_Q_WRNMAXLEN, S_CMD_R_BYTE,
- S_CMD_R_NBYTES, S_CMD_O_INIT, S_CMD_O_WRITEB, S_CMD_O_WRITEN,
- S_CMD_O_DELAY, S_CMD_O_EXEC.
- In addition, support for these commands is recommended:
- S_CMD_Q_PGMNAME, S_CMD_Q_BUSTYPE, S_CMD_Q_CHIPSIZE (if parallel).
-
-See also serprog.c
diff --git a/doc/classic_cli_manpage.rst b/doc/classic_cli_manpage.rst
index f40d19e..beafd82 100644
--- a/doc/classic_cli_manpage.rst
+++ b/doc/classic_cli_manpage.rst
@@ -749,7 +749,7 @@
The particular programmer implementation needs to support this feature, for it to work. If the requested chip
select isn't available, flashrom will fail safely.
-More information about serprog is available in **serprog-protocol.txt** in the source distribution.
+More information about serprog is available in this document: :doc:`/supported_hw/supported_prog/serprog/serprog-protocol`.
buspirate_spi programmer
diff --git a/doc/index.rst b/doc/index.rst
index 60c42b0..f32f182 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,6 +12,7 @@
dev_guide/index
user_docs/index
contrib_howtos/index
+ supported_hw/index
classic_cli_manpage
contact
release_notes/index
diff --git a/doc/supported_hw/index.rst b/doc/supported_hw/index.rst
new file mode 100644
index 0000000..5552326
--- /dev/null
+++ b/doc/supported_hw/index.rst
@@ -0,0 +1,8 @@
+==================
+Supported hardware
+==================
+
+.. toctree::
+ :maxdepth: 3
+
+ supported_prog/index
diff --git a/doc/supported_hw/supported_prog/index.rst b/doc/supported_hw/supported_prog/index.rst
new file mode 100644
index 0000000..9d71578
--- /dev/null
+++ b/doc/supported_hw/supported_prog/index.rst
@@ -0,0 +1,7 @@
+Supported programmers
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ serprog/index
diff --git a/doc/supported_hw/supported_prog/serprog/166px-Serprogduino_v2.jpeg b/doc/supported_hw/supported_prog/serprog/166px-Serprogduino_v2.jpeg
new file mode 100644
index 0000000..ffe8558
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/166px-Serprogduino_v2.jpeg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/250px-Arduino_5V_lpc_spi_shield.jpg b/doc/supported_hw/supported_prog/serprog/250px-Arduino_5V_lpc_spi_shield.jpg
new file mode 100644
index 0000000..1886e26
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/250px-Arduino_5V_lpc_spi_shield.jpg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/250px-Arduino_lpcspi_shield_render.png b/doc/supported_hw/supported_prog/serprog/250px-Arduino_lpcspi_shield_render.png
new file mode 100644
index 0000000..02b139e
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/250px-Arduino_lpcspi_shield_render.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-AtmegaXXu2-flasher.jpg b/doc/supported_hw/supported_prog/serprog/300px-AtmegaXXu2-flasher.jpg
new file mode 100644
index 0000000..1a78faa
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-AtmegaXXu2-flasher.jpg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-Avr_rs232_programmer.jpg b/doc/supported_hw/supported_prog/serprog/300px-Avr_rs232_programmer.jpg
new file mode 100644
index 0000000..618037b
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-Avr_rs232_programmer.jpg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-HydraFW_Default_PinAssignment.png b/doc/supported_hw/supported_prog/serprog/300px-HydraFW_Default_PinAssignment.png
new file mode 100644
index 0000000..a9fd931
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-HydraFW_Default_PinAssignment.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-Serprog-stm32vcp.jpg b/doc/supported_hw/supported_prog/serprog/300px-Serprog-stm32vcp.jpg
new file mode 100644
index 0000000..39cc46d
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-Serprog-stm32vcp.jpg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-Serprog_0001.jpeg b/doc/supported_hw/supported_prog/serprog/300px-Serprog_0001.jpeg
new file mode 100644
index 0000000..af1bcaf
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-Serprog_0001.jpeg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/300px-Teensy31_lpcspi_flasher.jpg b/doc/supported_hw/supported_prog/serprog/300px-Teensy31_lpcspi_flasher.jpg
new file mode 100644
index 0000000..9289aae
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/300px-Teensy31_lpcspi_flasher.jpg
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P1v1_arduino328.png b/doc/supported_hw/supported_prog/serprog/P1v1_arduino328.png
new file mode 100644
index 0000000..0fd808b
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P1v1_arduino328.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P1v2_arduino1280.png b/doc/supported_hw/supported_prog/serprog/P1v2_arduino1280.png
new file mode 100644
index 0000000..7cd6cb9
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P1v2_arduino1280.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P2v1_resdivider.png b/doc/supported_hw/supported_prog/serprog/P2v1_resdivider.png
new file mode 100644
index 0000000..16d5dae
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P2v1_resdivider.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P2v2_oc_cs.png b/doc/supported_hw/supported_prog/serprog/P2v2_oc_cs.png
new file mode 100644
index 0000000..45ebe2d
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P2v2_oc_cs.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P2v3_buffer4050.png b/doc/supported_hw/supported_prog/serprog/P2v3_buffer4050.png
new file mode 100644
index 0000000..d2ebd8c
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P2v3_buffer4050.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P3v1_dil8_so8_spi.png b/doc/supported_hw/supported_prog/serprog/P3v1_dil8_so8_spi.png
new file mode 100644
index 0000000..3a2f134
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P3v1_dil8_so8_spi.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/P3v2_so16_spi.png b/doc/supported_hw/supported_prog/serprog/P3v2_so16_spi.png
new file mode 100644
index 0000000..7ae1379
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/P3v2_so16_spi.png
Binary files differ
diff --git a/doc/supported_hw/supported_prog/serprog/arduino_flasher.rst b/doc/supported_hw/supported_prog/serprog/arduino_flasher.rst
new file mode 100644
index 0000000..ada0519
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/arduino_flasher.rst
@@ -0,0 +1,227 @@
+===============
+Arduino flasher
+===============
+
+.. container:: danger, admonition
+
+ **WARNING**
+
+ Make sure that the Arduino SPI voltages and the flash chip voltages matches: Without any extra resistors or level shifter,
+ the Arduino Uno and Duemillanove SPI pins are at 5V, while most chips operate at 3.3v.
+
+Hardware basics
+===============
+
+You'll need to have:
+
+* a supported Arduino, these are
+
+ * any based on the ATmega328 (/168/88 will work with small changes too), like the Arduino Uno R3.
+ * Arduino Mega or Mega2560, but notice that the software has a different branch for them.
+
+* a way to convert the 5V logic levels to 3.3V (except if 3.3V arduino, these are rarer)
+* a 3.3V SPI flash chip that is supported by flashrom
+
+Notes:
+
+* The FTDI based usb-serial converters are the fastest.
+* 1.8V conversion isnt covered here, yet.
+
+There are some simple schematics included here (`source <https://github.com/flashrom/wiki-arduino-spi-example-schematics>`_).
+The idea is that you pick one version from each part 1 through 3, and connect the pin/net names.
+
+Part 1: The Arduino
+-------------------
+
+ATmega328 based ones:
+
+.. image:: P1v1_arduino328.png
+
+For the Arduino Megas:
+
+.. image:: P1v2_arduino1280.png
+
+Part 2: Level translation
+-------------------------
+
+There are a few options here, ranging from the simple resistors (v1) to a buffer chip (v3).
+
+One thing to remember about the resistor dividers is that they're not strong enough to do ISP.
+
+Here's the simple resistors:
+
+.. image:: P2v1_resdivider.png
+
+The part count for the resistor divider is 6 resistors of 2 types or 9 of one type.
+
+Here's one with 5 resistors, the downside is that you'll need to modify the firmware a little:
+
+.. image:: P2v2_oc_cs.png
+
+The 3rd version is using the DIP16 HEF4050 buffer chip:
+
+.. image:: P2v3_buffer4050.png
+
+Part 3: The SPI Flash chip
+--------------------------
+
+The DIL-8 and SOIC-8 versions connect like this:
+
+.. image:: P3v1_dil8_so8_spi.png
+
+For the SMD SOIC-16 chips the pinout is:
+
+.. image:: P3v2_so16_spi.png
+
+Gallery of some flashers
+========================
+
+.. image:: 166px-Serprogduino_v2.jpeg
+
+.. _arduino shield:
+
+Alternative: Shield with SPI and LPC/FWH for 5V Arduinos
+========================================================
+
+.. image:: 250px-Arduino_5V_lpc_spi_shield.jpg
+
+.. image:: 250px-Arduino_lpcspi_shield_render.png
+
+`Firmware and hardware sources <https://github.com/urjaman/frser-m328lpcspi>`_
+
+`Shield PCB shared at oshpark <https://oshpark.com/shared_projects/E6jwmbWy>`_
+
+* This shield and firmware was built for 5V ATMega328s with FTDI, variations to that will need adaptations in building the shield and/or in the firmware.
+ The Uno R3 will work with the fast-usbserial U2 firmware.
+* This shield uses a different pin for SPI CS than the other circuits on this page, and has LPC/FWH capability, thus different firmware.
+ Frser-duino does have the code for using the CS like in this shield, but you need to modify spihw.h.
+* Note: do check for any incompatibilities between your arduino and the shield, eg. the PD7 used as LPC CLK clashes with BT reset in BT arduinos.
+* For LPC/FWH, current (16/02/01) flashrom trunk will be really slow, please use this branch instead.
+
+Software and setup
+==================
+
+The Arduino Uno R3 and other arduinos with an ATmega8U2/16U2 as an usb-serial converter have lots of bugs in their usb-serial firmware
+that prevent it from operating at more than a limited 115200 baud. The frser-duino firmware works around this by default if you use the appropriate make target,
+but there exists a firmware that allows these to be used like the FTDI at 2Mbaud: `fast-usbserial <https://github.com/urjaman/fast-usbserial>`_.
+
+Setup
+-----
+
+Required software
+^^^^^^^^^^^^^^^^^
+
+To make it work you need:
+
+* A recent flashrom with the serprog protocol compiled in (most packaged versions do)
+* `frser-duino which runs on the arduino <https://github.com/urjaman/frser-duino>`_
+
+ * This page used to link to `serprog-duino <https://gitorious.org/gnutoo-personal-arduino-projects/serprog-duino>`_,
+ frser-duino should build in a similar fashion and has better serial buffering and some other features (spi speed setting).
+
+* The avr toolchain(avr-gcc, avr-libc,make etc...)
+
+Building the software
+^^^^^^^^^^^^^^^^^^^^^
+
+First get the firmware source::
+
+ $ git clone --recursive git://github.com/urjaman/frser-duino
+ $ cd frser-duino
+
+Then build it:
+
+For a board with a 8u2 or a 16u2::
+
+ $ make u2 && make flash-u2
+
+For a board with an ftdi::
+
+ $ make ftdi && make flash-ftdi
+
+Building for the Mega1280 or 2560
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As above, except use the branch for the 1280::
+
+ $ git clone --recursive git://github.com/urjaman/frser-duino -b arduino-mega-1280
+
+For the Mega2560, change the Makefile to target the correct MCU (replace 1280 with 2560). Please also verify that the avrdude command is as expected for your device.
+
+Running flashrom
+^^^^^^^^^^^^^^^^
+
+The right flashrom arguments are explained in the :doc:`/classic_cli_manpage`, or here.
+
+Available targets:
+
+* ftdi, flash-ftdi:
+ For the Arduinos with an FTDI
+ compatible flashrom arguments::
+
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+
+ Other boards using an hardware USB<->Serial converter might work too.
+
+* u2, flash-u2:
+ For the Arduino with a 8u2 or a 16u2
+ compatible flashrom arguments::
+
+ flashrom -p serprog:dev=/dev/ttyACM0:115200
+
+So for a board that has an ftdi that would give::
+
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+
+Speed
+^^^^^
+
+The speed is very dependant on the flash chip used:
+
+* Its capacity impacts the speed a lot, as you would expect.
+* The chip model as also a huge impact.
+
+Duemillanove
+^^^^^^^^^^^^
+
+With the duemillanove::
+
+ # time flashrom -p serprog:dev=/dev/ttyUSB0:2000000 -r duemillanove.rom
+ flashrom v0.9.7-r1711 on Linux 3.18.3-gnu-1 (i686)
+ flashrom is free software, get the source code at http://www.flashrom.org
+
+ Calibrating delay loop... delay loop is unreliable, trying to continue OK.
+ serprog: Programmer name is "serprog-duino"
+ Found Winbond flash chip "W25Q32.V" (4096 kB, SPI) on serprog.
+ Reading flash... done.
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000 -r duemillanove.rom
+
+we have::
+
+ 4.23s user 0.29s system 8% cpu 56.010 total
+
+Uno
+^^^
+
+With the Arduino uno::
+
+ # flashrom -p serprog:dev=/dev/ttyACM0:115200 -r uno.rom
+ flashrom v0.9.7-r1711 on Linux 3.18.3-gnu-1 (i686)
+ flashrom is free software, get the source code at http://www.flashrom.org
+
+ Calibrating delay loop... delay loop is unreliable, trying to continue OK.
+ serprog: Programmer name is "serprog-duino"
+ Found Winbond flash chip "W25Q32.V" (4096 kB, SPI) on serprog.
+ Reading flash... done.
+ flashrom -p serprog:dev=/dev/ttyACM0:115200 -r uno.rom
+
+we have::
+
+ 4.77s user 0.65s system 1% cpu 6:02.43 total
+
+Tested chips
+^^^^^^^^^^^^
+
+* SST25VF016B => huge issues, not recognized by the 3.3v version, had to use the 5v version which is over maximum allowed voltage,
+ also had to lower the serial speed to 115200, ultra slow to write(seem related to the chip itself, since that with the openmoko programmer it's even slower...)...
+* W25X80 works well in 3.3v mode(5v works also but it's highly not advised to use 5v)
diff --git a/doc/supported_hw/supported_prog/serprog/arduino_flasher_3.3v.rst b/doc/supported_hw/supported_prog/serprog/arduino_flasher_3.3v.rst
new file mode 100644
index 0000000..0f4b76c
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/arduino_flasher_3.3v.rst
@@ -0,0 +1,237 @@
+====================
+Arduino flasher 3.3v
+====================
+
+Introduction
+============
+
+This explains how to:
+
+* Easily lower the voltage of an arduino
+* Use that arduino to flash a coreboot image on a GM45 Thinkpad with a SOIC16 chip
+
+It requires:
+
+* An AVR Arduino at 5v
+* An USB<->Serial adapter capable of providing enough current to power up:
+
+ * The arduino
+ * The flash chip
+ * The circuits around the flash chip
+
+It was tested with:
+
+* An Arduino.org "nano version 3.3"
+* A Sparkfun "FTDI Basic 3v3" (Uses an FTDI FT232R)
+
+Caveats and warnings:
+
+* It requires you to to never connect an USB cable between the Arduino USB port and the computer while the flasher is connected to a flash chip.
+ This would result in the I/O voltage being 5V instead of 3.3V. If you think you may accidentally connect it this way, this flasher isn't the right solution for you.
+* You need to read the tutorial, if you don't understand it, it's probably not for you. In doubt you could ask for some help in flashrom real-time channels
+ or on the mailing list, see :doc:`/contact`.
+* For now it requires to patch frser-duino
+
+Theory
+========
+
+In the `Atmega328/P datasheet <https://web.archive.org/web/20181004225154/ww1.microchip.com/downloads/en/DeviceDoc/Atmel-42735-8-bit-AVR-Microcontroller-ATmega328-328P_Datasheet.pdf>`_,
+the "32.3. Speed Grades" chapter describes (pages 368 and 369) the link between maximum frequency of the microcontroller and the voltage. At 3.3v, the maximum frequency is 12Mhz.
+
+HOWTO
+========
+
+Build the code installing it on the arduino
+-------------------------------------------
+
+Building frser-duino
+^^^^^^^^^^^^^^^^^^^^
+
+First download frser-duino::
+
+ $ git clone --recursive https://github.com/urjaman/frser-duino.git
+ $ cd frser-duino
+
+Then modify the ``F_CPU`` value in ``main.h`` to be 12Mhz instead of 16Mhz. ``F_CPU`` will look like that::
+
+ #define F_CPU 16000000UL
+
+Change it to::
+
+ #define F_CPU 12000000UL
+
+You can then build the code::
+
+ $ make ftdi
+
+Installing the code on the arduino
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before installing the code on arduino we want to make sure that we are talking to the right device.
+To do that make sure that the arduino is not connected to your computer and run::
+
+ $ ls -l /dev/ttyUSB0
+
+If everything went fine it will output something like that::
+
+ ls: cannot access '/dev/ttyUSB0': No such file or directory
+
+If instead it looks like that::
+
+ crw-rw---- 1 root uucp 188, 0 27 févr. 14:30 /dev/ttyUSB0
+
+then something else is connected to your computer at ``/dev/ttyUSB0``. If you can't figure what's going on by yourself,
+it's better to try get help on the flashrom channels to fix the issue, see :doc:`/contact`.
+
+Then connect your arduino to the computer and run the same command::
+
+ $ ls -l /dev/ttyUSB0
+
+This time it's supposed to output a line that looks more or less like that::
+
+ crw-rw---- 1 root uucp 188, 0 27 févr. 14:30 /dev/ttyUSB0
+
+At this point we're pretty confident that ``/dev/ttyUSB0`` corresponds to the arduino, so we can install the code with::
+
+ $ make flash-ftdi
+
+Once it is installed we can now test that everything went fine with::
+
+ $ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+
+This will make flashrom talk to the arduino to verify if everything is fine up to this point.
+
+If everything went fine it will look more or less like that::
+
+ $ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+ /sys/firmware/dmi/tables/smbios_entry_point: Permission denied
+ /dev/mem: Permission denied
+ /sys/firmware/dmi/tables/smbios_entry_point: Permission denied
+ /dev/mem: Permission denied
+ flashrom v1.0 on Linux 4.15.2-gnu-1 (i686)
+ flashrom is free software, get the source code at https://flashrom.org
+
+ Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
+ serprog: Programmer name is "frser-duino"
+ serprog: requested mapping AT45CS1282 is incompatible: 0x1080000 bytes at 0xfef80000.
+ No EEPROM/flash device found.
+ Note: flashrom can never write if the flash chip isn't found automatically.
+
+This is the important line::
+
+ serprog: Programmer name is "frser-duino"
+
+It means that flashrom is able to talk to the flasher, which reports itself as "frser-duino" We also have the following line::
+
+ No EEPROM/flash device found.
+
+which tells that it didn't find any flash. This is what's supposed to happen since we didn't connect any yet.
+
+Build the programmer
+--------------------
+
+Connect the programmer to the USB<->Serial adapter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To do that:
+
+* Connect the FTDI adapter RX to the TX of the arduino
+* Connect the FTDI adapter TX to the RX of the arduino
+* Connect the 3V3 of the FTDI adapter to the 5V pin of the Arduino
+* Connect the GND of the FTDI adapter to the GDN of the arduino.
+
+Here's a summary of the above:
+
+======== =========================
+Arduino USB<->Serial port adapter
+======== =========================
+RX TX
+TX RX
+5v 3.3v
+GND GND
+======== =========================
+
+You can now check that the programmer is responding with::
+
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+
+Since you didn't connect yet a flash chip, it will says it found no flash chips::
+
+ $ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+ /sys/firmware/dmi/tables/smbios_entry_point: Permission denied
+ /dev/mem: Permission denied
+ /sys/firmware/dmi/tables/smbios_entry_point: Permission denied
+ /dev/mem: Permission denied
+ flashrom v1.0 on Linux 4.15.2-gnu-1 (i686)
+ flashrom is free software, get the source code at https://flashrom.org
+
+ Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
+ serprog: Programmer name is "frser-duino"
+ serprog: requested mapping AT45CS1282 is incompatible: 0x1080000 bytes at 0xfef80000.
+ No EEPROM/flash device found.
+ Note: flashrom can never write if the flash chip isn't found automatically.
+
+Again like before the important parts are::
+
+ serprog: Programmer name is "frser-duino"
+
+And::
+
+ No EEPROM/flash device found.
+
+If you made it up to this point, you successfully built the flasher.
+
+Using the programmer
+--------------------
+
+Connect the programmer to a flash chip
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since the flasher has been built, you probably want to use it.
+
+If you use a clip (Like a SOIC-8 or SOIC16 Pomona clip), connect it to the Arduino
+Connect the chip to the clip, or if you don't use a clip, the chip to the Arduino
+Here's how to connect the flash chips to the programmer:
+
+=========== ========================== =================== =====================
+Arduino pin Function Flash chip pin name SOIC16 Flash chip pin
+=========== ========================== =================== =====================
+D13 CLK (Clock) CLK 16
+D12 MISO (Master In Slave Out) MISO or SO 8
+D11 MOSI (Master Out Slave In) MOSI or SI 15
+D10 CS# (Chip Select) CS# or CS OR SS 7
+GND GND (Ground) GND 10
+5V 3.3V VCC 2
+5V 3.3V WP# (Write Protect) 9
+5V 3.3V HOLD# 1
+=========== ========================== =================== =====================
+
+Then connect an USB cable between the USB<->Serial adapter and the computer.
+Never connect the cable between the Arduino USB port and the computer while the flasher is connected to a flash chip.
+That would result in the I/O voltage being 5V instead of 3.3V.
+
+Flashing
+^^^^^^^^
+
+Run flashrom like that::
+
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000
+
+With some models of Macronix flash chip (that are present in the Thinkpad X200) you might need to add ``spispeed=100k`` like that::
+
+ flashrom -p serprog:dev=/dev/ttyUSB0:2000000,spispeed=100k
+
+Thanks
+========
+
+Thanks a lot to SwiftGeek on IRC (#libreboot on Libera) for finding the first workaround to make it detect flash chips at lower voltage.
+Thanks also for telling me about the Macronix issues on the Thinkpad X200. This project would not have been possible without that.
+
+Page license
+============
+
+This page is available under the following licenses:
+
+* `CC-BY-SA 3.0 <https://creativecommons.org/licenses/by-sa/3.0/legalcode>`_
+* `CC-BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_ or later
+* `GFDL 1.3 <https://www.gnu.org/licenses/fdl-1.3.txt>`_ or later
diff --git a/doc/supported_hw/supported_prog/serprog/index.rst b/doc/supported_hw/supported_prog/serprog/index.rst
new file mode 100644
index 0000000..c1c2d73
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/index.rst
@@ -0,0 +1,11 @@
+Serprog
+========
+
+.. toctree::
+ :maxdepth: 1
+
+ overview
+ serprog-protocol
+ arduino_flasher_3.3v
+ arduino_flasher
+ teensy_3_1
diff --git a/doc/supported_hw/supported_prog/serprog/overview.rst b/doc/supported_hw/supported_prog/serprog/overview.rst
new file mode 100644
index 0000000..cde31eb
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/overview.rst
@@ -0,0 +1,85 @@
+==================
+Serprog (overview)
+==================
+
+This page collects information about the serprog protocol and the programmers implementing it.
+
+Protocol
+========
+
+See :doc:`/supported_hw/supported_prog/serprog/serprog-protocol`. It is designed to be compact and allow efficient storage in limited memory of programmer devices.
+
+AVR flasher by Urja Rannikko
+============================
+
+.. image:: 300px-Avr_rs232_programmer.jpg
+
+The Prototype RS232 AVR parallel flash programmer of Urja Rannikko was the first implementation of the serprog protocol.
+
+The source code can be found `here <https://github.com/urjaman/frser-atmega88>`_.
+
+InSystemFlasher by Juhana Helovuo
+=================================
+
+This was the first one that talks to SPI devices via serial over USB.
+Details can be found in the `coreboot wiki <https://www.coreboot.org/InSystemFlasher>`_ and in this
+`coreboot mailing list thread <https://mail.coreboot.org/pipermail/coreboot/2011-February/063349.html>`_.
+
+atmegaXXu2-flasher by Stefan Tauner
+===================================
+
+Like the InSystemFlasher this one uses LUFA on an AVR microcontroller to tunnel the serial data over USB.
+
+.. image:: 300px-AtmegaXXu2-flasher.jpg
+
+Various Arduino based flashers
+==============================
+
+Frser-duino
+-----------
+
+This project contains `source code <https://github.com/urjaman/frser-duino/>`_ to install on Arduino devices.
+
+This developer also have various ports on `github repo <https://github.com/urjaman?tab=repositories>`_ for several microcontroller boards, such as:
+
+* `frser-teensyflash <https://github.com/urjaman/frser-teensyflash>`_: A port for the teensy microcontroller board
+
+There also various other interesting projects such as:
+
+* `fast-usbserial <https://github.com/urjaman/fast-usbserial>`_: A software to make arduino with 8u2 or 16u2 flashing faster and more reliable]
+* :ref:`arduino shield`
+
+Using a 5v Arduino at 3.3V
+--------------------------
+
+Information on it can be found in this doc: :doc:`/supported_hw/supported_prog/serprog/arduino_flasher_3.3v`
+
+5V arduino with level shifter
+-----------------------------
+
+For detailed instructions on how to use different Arduino models to access SPI flash chips see :doc:`/supported_hw/supported_prog/serprog/arduino_flasher`
+
+.. image:: 300px-Serprog_0001.jpeg
+
+Teensy 3.1 SPI + LPC/FWH Flasher
+--------------------------------
+
+A Teensy 3.1 based small flasher by Urja Rannikko documented here: :doc:`/supported_hw/supported_prog/serprog/teensy_3_1`
+
+HydraBus multi-tool
+-------------------
+
+HydraBus (hardware) with HydraFW (firmware) is an open source multi-tool for learning, developing, debugging, hacking and penetration testing
+of embedded hardware. It is built upon an ARM Cortex-M4 (STM32F405). The source code for HydraFW is available
+`on GitHub <https://github.com/hydrabus/hydrafw>`_. Refer to `their GitHub Wiki <https://github.com/hydrabus/hydrafw/wiki/HydraFW-SPI-guide#flashrom-usage>`_
+for more details on how to use HydraBus with flashrom.
+
+.. image:: 300px-HydraFW_Default_PinAssignment.png
+
+serprog-stm32vcp by Chi Zhang
+-----------------------------
+
+The most powerful serprog-based programmer is built upon an ARM Cortex-M3 (STM32F103) featuring up to 36 MHz SPI clock.
+See `the github page <https://github.com/dword1511/serprog-stm32vcp#serprog-stm32vcp>`_ for further details, source code etc.
+
+.. image:: 300px-Serprog-stm32vcp.jpg
diff --git a/doc/supported_hw/supported_prog/serprog/serprog-protocol.rst b/doc/supported_hw/supported_prog/serprog/serprog-protocol.rst
new file mode 100644
index 0000000..35574fa
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/serprog-protocol.rst
@@ -0,0 +1,150 @@
+=====================================
+Serial Flasher Protocol Specification
+=====================================
+
+Version 1 (0x01 return value == 1)
+==================================
+
+Command And Answer Sequence - all commands give an answer.
+
+PC: COMMAND(8bit) <parameters determined by opcode>
+
+DEV: ACK/NAK(8bit) <OPTIONAL RETURN BYTES (only if ACK)> / nothing
+
+Command 0x10 (SYNCNOP) has a special return of NAK+ACK for synchronization.
+
+ACK = 0x06
+
+NAK = 0x15
+
+All multibyte values are little-endian. Addresses and lengths are 24-bit.
+
+======== =============================== ================================================== =================================================
+COMMAND Description Parameters Return Value
+======== =============================== ================================================== =================================================
+0x00 NOP none ACK
+0x01 Query programmer iface version none ACK + 16bit version (nonzero)
+0x02 Query supported commands bitmap none ACK + 32 bytes (256 bits) of supported cmds flags
+0x03 Query programmer name none ACK + 16 bytes string (null padding) / NAK
+0x04 Query serial buffer size none ACK + 16bit size / NAK
+0x05 Query supported bustypes none ACK + 8-bit flags (as per flashrom) / NAK
+0x06 Query connected address lines none ACK + 8bit line count / NAK
+0x07 Query operation buffer size none ACK + 16bit size / NAK
+0x08 Query maximum write-n length none ACK + 24bit length (0==2^24) / NAK
+0x09 Read byte 24-bit addr ACK + BYTE / NAK
+0x0A Read n bytes 24-bit addr + 24-bit length ACK + length bytes / NAK
+0x0B Initialize operation buffer none ACK / NAK
+0x0C Write to opbuf: Write byte 24-bit addr + 8-bit byte ACK / NAK (NOTE: takes 5 bytes in opbuf)
+0x0D Write to opbuf: Write n 24-bit length + 24-bit addr + length bytes of data ACK / NAK (NOTE: takes 7+n bytes in opbuf)
+0x0E Write to opbuf: delay 32-bit usecs ACK / NAK (NOTE: takes 5 bytes in opbuf)
+0x0F Execute operation buffer none ACK / NAK
+0x10 Sync NOP none NAK + ACK (for synchronization)
+0x11 Query maximum read-n length none ACK + 24-bit length (0==2^24) / NAK
+0x12 Set used bustype 8-bit flags (as with 0x05) ACK / NAK
+0x13 Perform SPI operation 24-bit slen + 24-bit rlen + slen bytes of data ACK + rlen bytes of data / NAK
+0x14 Set SPI clock frequency in Hz 32-bit requested frequency ACK + 32-bit set frequency / NAK
+0x15 Toggle flash chip pin drivers 8-bit (0 disable, else enable) ACK / NAK
+0x16 Set SPI Chip Select 8-bit ACK / NAK
+0x17 Set SPI Mode 8-bit ACK / NAK
+0x18 Set CS Mode 8-bit ACK / NAK
+0x?? unimplemented command - invalid
+======== =============================== ================================================== =================================================
+
+Additional information of the above commands:
+
+ About unimplemented commands / startup sequence:
+ Only commands allowed to be used without checking anything are 0x00,0x10 and 0x01 (NOP,SYNCNOP,Q_IFACE).
+ If 0x01 doesn't return 1, dont do anything if you dont support a newer protocol.
+ Then, check support for any other opcode (except 0x02) by using 0x02 (Q_CMDMAP).
+
+ 0x02 (Q_CMDMAP):
+ The map's bits are mapped as follows:
+ cmd 0 support: byte 0 bit 0
+ cmd 1 support: byte 0 bit 1
+ cmd 7 support: byte 0 bit 7
+ cmd 8 support: byte 1 bit 0, and so on.
+
+ 0x04 (Q_SERBUF):
+ If the programmer has a guaranteed working flow control,
+ it should return a big bogus value - eg 0xFFFF.
+
+ 0x05 (Q_BUSTYPE):
+ The bit's are defined as follows:
+ bit 0: PARALLEL, bit 1: LPC, bit 2: FWH, bit 3: SPI.
+
+ 0x06 (Q_CHIPSIZE):
+ Only applicable to parallel programmers.
+ An LPC/FWH/SPI-programmer can report this as not supported in the command bitmap.
+
+ 0x08 (Q_WRNMAXLEN):
+ If a programmer reports a bigger maximum write-n length than the serial buffer size,
+ it is assumed that the programmer can process the data fast enough to take in the
+ reported maximum write-n without problems.
+
+ 0x0F (O_EXEC):
+ Execute operation buffer will also clear it, regardless of the return value.
+
+ 0x11 (Q_RDNMAXLEN):
+ If this command is not supported, assume return of 0 (2^24).
+
+ 0x12 (S_BUSTYPE):
+ Set's the used bustype if the programmer can support more than one flash protocol.
+ Sending a byte with more than 1 bit set will make the programmer decide among them
+ on it's own. Bit values as with Q_BUSTYPE.
+
+ 0x13 (O_SPIOP):
+ Send and receive bytes via SPI.
+ Maximum slen is Q_WRNMAXLEN in case Q_BUSTYPE returns SPI only or S_BUSTYPE was used
+ to set SPI exclusively before. Same for rlen and Q_RDNMAXLEN.
+ This operation is immediate, meaning it doesn't use the operation buffer.
+
+ 0x14 (S_SPI_FREQ):
+ Set the SPI clock frequency. The 32-bit value indicates the
+ requested frequency in Hertz. Value 0 is reserved and should
+ be NAKed by the programmer. The requested frequency should be
+ mapped by the programmer software to a supported frequency
+ lower than the one requested. If there is no lower frequency
+ available the lowest possible should be used. The value
+ chosen is sent back in the reply with an ACK.
+
+ 0x15 (S_PIN_STATE):
+ Sets the state of the pin drivers connected to the flash chip. Disabling them allows other
+ devices (e.g. a mainboard's chipset) to access the chip. This way the serprog controller can
+ remain attached to the flash chip even when the board is running. The user is responsible to
+ NOT connect VCC and other permanently externally driven signals to the programmer as needed.
+ If the value is 0, then the drivers should be disabled, otherwise they should be enabled.
+
+ 0x16 (S_SPI_CS):
+ Set which SPI Chip Select pin to use. This operation is immediate,
+ meaning it doesn't use the operation buffer.
+
+ 0x17 (S_SPI_MODE):
+ Set which SPI Mode to use for 0x13 O_SPIOP commands.
+ This operation is immediate, meaning it doesn't use the operation buffer.
+ The current defined modes are:
+
+ * 0x00: SPI Half Duplex (default)
+ * 0x01: SPI Full Duplex
+
+ 0x18 (S_CS_MODE):
+ Set which CS Mode to use. The CS Mode determines the CS behaviour.
+ This allows manual control over the CS.
+ This operation is immediate, meaning it doesn't use the operation buffer.
+ The current defined modes are:
+
+ * 0x00: CS Auto Mode. The CS gets selected before 0x13 O_SPIOP commands and
+ deselected afterwards. (default)
+ * 0x01: CS Selected. The CS will be selected until another mode is set.
+ * 0x02: CS Deselected. The CS will be deselected until another mode is set.
+
+ About mandatory commands:
+ The only truly mandatory commands for any device are 0x00, 0x01, 0x02 and 0x10,
+ but one can't really do anything with these commands.
+ Support for the following commands is necessary for flashrom to operate properly:
+ S_CMD_Q_SERBUF, S_CMD_Q_OPBUF, S_CMD_Q_WRNMAXLEN, S_CMD_R_BYTE,
+ S_CMD_R_NBYTES, S_CMD_O_INIT, S_CMD_O_WRITEB, S_CMD_O_WRITEN,
+ S_CMD_O_DELAY, S_CMD_O_EXEC.
+ In addition, support for these commands is recommended:
+ S_CMD_Q_PGMNAME, S_CMD_Q_BUSTYPE, S_CMD_Q_CHIPSIZE (if parallel).
+
+See also ``serprog.c``
diff --git a/doc/supported_hw/supported_prog/serprog/teensy_3_1.rst b/doc/supported_hw/supported_prog/serprog/teensy_3_1.rst
new file mode 100644
index 0000000..2336387
--- /dev/null
+++ b/doc/supported_hw/supported_prog/serprog/teensy_3_1.rst
@@ -0,0 +1,81 @@
+================================
+Teensy 3.1 SPI + LPC/FWH Flasher
+================================
+
+Note: this was made for the Teensy 3.1, but 3.2 should be compatible too.
+
+Hardware
+========
+
+.. image:: 300px-Teensy31_lpcspi_flasher.jpg
+
+The hardware is made of a `Teensy 3.1 <https://www.pjrc.com/teensy/teensy31.html>`_ and a shield-like PCB over it.
+Schematic and board files for the PCB can be found `in the github <https://github.com/urjaman/frser-teensyflash/tree/master/hardware>`_.
+The PCB is also shared `at OshPark <https://oshpark.com/shared_projects/izukIxq8>`_.
+
+Other components required:
+
+* pin headers (total 28, but get more)
+* a DIL8 socket (if you want to use SPI DIL8)
+* a PLCC32 SMD socket (if you want to use LPC/FWH)
+* optional: small SMD capacitor - pad exists under the shield PCB
+
+Assembly
+--------
+
+* start by installing the SMD cap (if available) and the DIL8 socket on the shield PCB
+* split appropriate strips of pin headers for the teensy and solder them on the teensy, you can use the shield pcb to align them
+
+ * my arrangement was as pictured in order to have more ground clearance under the teensy for the prog button
+
+* push the shield pcb only a little bit on the pin headers, just so the headers dont come over the top of the PCB
+* solder two corner pins to keep the shield PCB in place, these can be done from above
+* solder the rest of headers from the underside while watching that you dont flood the topside with too much solder, especially for the ones close to the PLCC socket
+* in order to solder the SMD PLCC32 socket, you'll need to break out the middle plastic bit, but keep it safe
+
+ * to protect from solder bridges forming between the pin headers and PLCC socket, i placed a very thin tape over the pin header holes on the pcb during the soldering
+ * notice that the PLCC footprint isnt centered on the PCB, meaning dont try to align the PLCC socket exactly on the PCB
+
+* after soldering the PLCC socket, i installed the plastic bit back with a little bit of glue
+
+Software
+========
+
+Firmware for the Teensy is available at https://github.com/urjaman/frser-teensyflash
+
+Also see the README in that directory, both it or this document might be outdated ;)
+
+As of writing the setup would be:
+
+* download arduino, extract it somewhere where you have write access
+* download the `Teensyduino thingy <https://www.pjrc.com/teensy/td_download.html>`_
+* run it on that arduino tree
+* install the udev rules provided in the above url
+* compile and install the `teensy_loader_cli <https://www.pjrc.com/teensy/loader_cli.html>`_ in your path
+
+ ::
+
+ git clone --recursive https://github.com/urjaman/frser-teensyflash.git
+ cd frser-teensyflash
+ nano Makefile # Edit the TEENSYDIR path to include your arduino directory
+ make
+ make program-cli # If this waits you need to press the PROG button on the teensy
+
+After this you should be able to use it with flashrom serprog, for speedups and enhancements to serprog before they're upstreamed
+I'd suggest to use this flashrom tree: https://github.com/urjaman/flashrom/tree/sp-upstream3
+
+Device should be something like /dev/ttyACM0 and the baudrate doesnt matter::
+
+ flashrom -p serprog:dev=/dev/ttyACM0:2000000
+
+ISP Usage
+---------
+
+The same software could be used on a bare teensy 3.1 for ISP SPI programming - this is untested and also the 3.3V supply in the teensy is not strong, so beware, but the SPI pins used would be:
+
+* CS: "Pin 2", PD0
+* SCK: "Pin 14", PD1
+* MOSI: "Pin 7", PD2
+* MISO: "Pin 8", PD3
+
+See https://forum.pjrc.com/threads/25643-Combined-Pin-Assignments-card for a good Teensy pinmap picture.
To view, visit change 82018. To unsubscribe, or for help writing mail filters, visit settings.