--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Icestick-instructions	Sun Sep 10 07:30:01 2023 +0000
@@ -0,0 +1,61 @@
+If you have a Lattice iCEstick FPGA board (ICE40HX1K-STICK-EVN) and you wish to
+program its FT2232H subsystem EEPROM with a sensible configuration that results
+in the Linux kernel ftdi_sio driver leaving Channel A untouched and creating a
+single ttyUSB device for Channel B, follow these instructions:
+
+1) Plug your iCEstick board into your PC/laptop or other Linux host, and run
+   lsusb.  There should be one particular line in lsusb output that reads like
+   this:
+
+Bus 001 Device 014: ID 0403:6010 Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC
+
+or perhaps like this on older systems:
+
+Bus 001 Device 014: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC
+
+Bus and device numbers will be different on your system, but the important part
+is ID 0403:6010 - it is the default USB ID of FT2232x chips that appears when
+no custom ID has been assigned via the EEPROM.
+
+2) Ensure that you don't have any other USB devices with ID 0403:6010 - given
+   that it is the chip's default, lots of devices use it!
+
+Make sure that there is only one line in lsusb output that reads ID 0403:6010.
+Unplug your iCEstick and make sure that this line disappears.  Plug it back in
+and make sure the line reappears.
+
+3) Once you are sure that you won't hit some other USB device using the same
+   popular ID code, execute this programming command pipeline:
+
+ftee-gen2232h -b icestick | fteeprom-prog i:0x0403:0x6010
+
+This shell pipeline is a little long and looks complicated, but it must be
+issued exactly as listed above.  The first part of the pipeline generates an
+image for an FT2232H chip (ftee-gen2232h) with 93C56 EEPROM (-b option) based
+on standard (shipped with fc-usbser-tools) configuration named "icestick"; the
+second part of the pipeline sends physical EEPROM write commands (USB control
+endpoint requests, FTDI-specific) to the USB device matching the given ID.
+
+4) Unplug and replug the iCEstick for the EEPROM change to take effect.  Run
+   lsusb again and note that the USB ID is now 0403:7150 instead of 0403:6010 -
+   still within FTDI's vendor ID, but with a specific, non-default product ID
+   code.
+
+With the new ID the Linux kernel ftdi_sio driver should create a ttyUSB device
+only for FT2232H Channel B, which is the UART channel for talking to user logic
+inside the FPGA.  I (Mother Mychaela) also recommend that you create an
+iceprog-7150 wrapper around the standard iceprog utility from IceStorm toolkit,
+in the form of a shell script like this:
+
+#!/bin/sh
+exec /usr/local/bin/iceprog -d i:0x0403:0x7150 "$@"
+
+It looks like Claire (the author of IceStorm) was not as bothered as I am by
+the bogosity of a ttyUSB device for the MPSSE channel that appears on plug-in
+but then disappears once you run a userspace program that exercises MPSSE via
+libftdi: she coded iceprog to look for 0403:6010 in the absence of a -d option
+giving a custom device selector string, rather than doing something similar to
+what I did.  With standard iceprog being as it is, we need to run it with this
+-d option when we have programmed the FT2232H EEPROM to use a more sensible USB
+ID, and in my opinion the most sane way to supply this needed option is via a
+wrapper as recommended above.