annotate doc/Icestick-instructions @ 68:5cbde3c80c24

fteeprom-{erase,prog}: detach logic: change to detach by default As it turns out, detaching all ttyUSB interfaces of a multichannel device does not require outside knowledge of how many channels there are, as in our previous -d option design that is being removed here - instead we can read the bNumInterfaces constant from the USB device's config descriptor and thus know how many interfaces there are in total. Based on this discovery, change the design of fteeprom-{erase,prog} as follows: * remove -d option; * flip the default to where we detach all interfaces by default; * add -n option to NOT detach any interfaces.
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 13 Sep 2023 06:37:03 +0000
parents 6bf063ade588
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 If you have a Lattice iCEstick FPGA board (ICE40HX1K-STICK-EVN) and you wish to
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 program its FT2232H subsystem EEPROM with a sensible configuration that results
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 in the Linux kernel ftdi_sio driver leaving Channel A untouched and creating a
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 single ttyUSB device for Channel B, follow these instructions:
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 1) Plug your iCEstick board into your PC/laptop or other Linux host, and run
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 lsusb. There should be one particular line in lsusb output that reads like
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 this:
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Bus 001 Device 014: ID 0403:6010 Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 or perhaps like this on older systems:
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 Bus 001 Device 014: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 Bus and device numbers will be different on your system, but the important part
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 is ID 0403:6010 - it is the default USB ID of FT2232x chips that appears when
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 no custom ID has been assigned via the EEPROM.
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 2) Ensure that you don't have any other USB devices with ID 0403:6010 - given
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 that it is the chip's default, lots of devices use it!
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 Make sure that there is only one line in lsusb output that reads ID 0403:6010.
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 Unplug your iCEstick and make sure that this line disappears. Plug it back in
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 and make sure the line reappears.
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 3) Once you are sure that you won't hit some other USB device using the same
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 popular ID code, execute this programming command pipeline:
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 ftee-gen2232h -b icestick | fteeprom-prog i:0x0403:0x6010
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 This shell pipeline is a little long and looks complicated, but it must be
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 issued exactly as listed above. The first part of the pipeline generates an
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 image for an FT2232H chip (ftee-gen2232h) with 93C56 EEPROM (-b option) based
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 on standard (shipped with fc-usbser-tools) configuration named "icestick"; the
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 second part of the pipeline sends physical EEPROM write commands (USB control
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 endpoint requests, FTDI-specific) to the USB device matching the given ID.
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 4) Unplug and replug the iCEstick for the EEPROM change to take effect. Run
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 lsusb again and note that the USB ID is now 0403:7150 instead of 0403:6010 -
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 still within FTDI's vendor ID, but with a specific, non-default product ID
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 code.
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 With the new ID the Linux kernel ftdi_sio driver should create a ttyUSB device
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 only for FT2232H Channel B, which is the UART channel for talking to user logic
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 inside the FPGA. I (Mother Mychaela) also recommend that you create an
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 iceprog-7150 wrapper around the standard iceprog utility from IceStorm toolkit,
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 in the form of a shell script like this:
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 #!/bin/sh
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 exec /usr/local/bin/iceprog -d i:0x0403:0x7150 "$@"
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 It looks like Claire (the author of IceStorm) was not as bothered as I am by
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 the bogosity of a ttyUSB device for the MPSSE channel that appears on plug-in
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 but then disappears once you run a userspace program that exercises MPSSE via
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 libftdi: she coded iceprog to look for 0403:6010 in the absence of a -d option
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 giving a custom device selector string, rather than doing something similar to
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 what I did. With standard iceprog being as it is, we need to run it with this
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 -d option when we have programmed the FT2232H EEPROM to use a more sensible USB
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 ID, and in my opinion the most sane way to supply this needed option is via a
6bf063ade588 doc/Icestick-instructions: new article
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 wrapper as recommended above.