view doc/Icestick-instructions @ 107:bc3367755586 default tip

add INSTALL document
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 21 Nov 2023 22:11:09 +0000
parents 6bf063ade588
children
line wrap: on
line source

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.