doc: Convert serprog docs to rst and add to doc directory

Change-Id: Ie52f1e051ed215d61d5fb535e3eddeac71f64d13
Signed-off-by: Anastasia Klimchuk <aklm@flashrom.org>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/82018
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Sydney <git@funkeleinhorn.com>
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>

doc/classic_cli_manpage.rst

@@ -749,7 +749,7 @@ chips at once and selecting which one to flash by software means (rather than re
 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

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

doc/supported_hw/index.rst

@@ -0,0 +1,8 @@
+==================
+Supported hardware
+==================
+
+.. toctree::
+    :maxdepth: 3
+
+    supported_prog/index

doc/supported_hw/supported_prog/index.rst

@@ -0,0 +1,7 @@
+Supported programmers
+=====================
+
+.. toctree::
+    :maxdepth: 2
+
+    serprog/index

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)

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

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

doc/supported_hw/supported_prog/serprog/overview.rst

@@ -0,0 +1,83 @@
+==================
+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
+
+stm32-vserprog by Chi Zhang
+-----------------------------
+
+A powerful option is `stm32-vserprog <https://github.com/dword1511/stm32-vserprog#stm32-vserprog>`_, a firmware for various STM32-based boards
+that turns them into serprog-based programmers with SPI clock speeds up to 36 MHz.

doc/supported_hw/supported_prog/serprog/serprog-protocol.rst

@@ -1,83 +1,103 @@
-Serial Flasher Protocol Specification - version 1 (0x01 return value == 1)
+=====================================
+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.
-
+======== =============================== ================================================== =================================================
+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
@@ -86,30 +106,37 @@ Additional information of the above commands:
 		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
+
+			* 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.
+
+			* 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.
@@ -120,4 +147,4 @@ Additional information of the above commands:
 		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
+See also ``serprog.c``

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.