FreeCalypso > hg > fc-usbser-tools

comparison doc/Unbuffered-FT2232x-JTAG @ 34:f5fbcf1ff032

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: initial import from freecalypso-hwlab
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 09 Sep 2023 21:28:02 +0000
parents
children
comparison
equal deleted inserted replaced
33:df284688d0c8 34:f5fbcf1ff032
1 How to make a safe JTAG adapter out of a generic unbuffered FT2232x board
2 =========================================================================
3
4 Among the FOSS community of tinkerers who use OpenOCD to operate on the JTAG
5 interfaces of various hardware targets, one of the most common JTAG adapter
6 choices (if not the most common) is to use some adapter gadget based on an FTDI
7 chip, most commonly one of FT2232x variants. However, a major distinction needs
8 to be drawn between specialized purpose-made JTAG adapter products which just
9 happen to use an FT2232x chip internally, versus generic FT2232x breakout boards
10 which the user wires up for JTAG on his or her own.
11
12 In an ideal world, using a purpose-made buffered JTAG adapter (one that has a
13 buffer inserted between FT2232x I/O pins and the target connection interface)
14 would be strongly preferable for a whole host of reasons. However, to this
15 author's disappointment, there are very few community vendors who make such
16 adapters, and I was NOT able to find any high-quality buffered JTAG adapter
17 which can be bought in the present and which comes with published schematics.
18 (There is one very well-known vendor of "community" JTAG adapters who refuses
19 to publish schematics for their current model; they have an older model for
20 which they did publish schematics, but it is discontinued and they are not
21 interested in bringing it back into production or handing the complete design
22 over to the community - probably because it would then compete with their
23 current sans-schematics product! Selling JTAG adapters to the community while
24 keeping their schematics secret is just assinine, and I refuse to give my
25 business to such vendors.)
26
27 Given the current sorry state of availability of buffered JTAG adapters, I have
28 given more thought to the unbuffered option, and I found what appears to be a
29 way to make them safe - but my method requires programming the EEPROM on the
30 FT2232x board with a special custom configuration, and in this article I am
31 going to provide the full details and instructions.
32
33 To begin with, an unbuffered JTAG adapter (one in which the target JTAG signals
34 are connected directly to FT2232x I/O pins without any buffer in between) can
35 work only with targets that operate their JTAG interface at 3.3 V, or perhaps
36 a slightly lower but still fully 3.3V-compatible logic voltage level like the
37 2.8 V I/O on Calypso GSM baseband processors. An unbuffered adapter CANNOT
38 work with, say, a 1.8 V JTAG interface - but as long as your target runs at
39 3.3 or 2.8 V, then we can continue.
40
41 The next big problem with unbuffered FT2232x adapters is that if you don't put
42 a special configuration in the EEPROM (or if your FT2232x board omits the EEPROM
43 altogether), the channel which you are going to wire up for JTAG (can only be
44 Channel A on FT2232C/D, can be either channel on FT2232H) is going to come up
45 in FTDI's default UART mode on power-up, and it is going to stay in that mode
46 until and unless you run OpenOCD, which will then switch it into MPSSE mode for
47 JTAG. Why is it a problem? Answer: you need to connect the TDO line from the
48 target to the FT2232x chip's ADBUS2 pin for JTAG to work via MPSSE, but in the
49 power-up default UART mode this ADBUS2 pin is the RTS output. FT2232x RTS
50 output fighting with the target's TDO output - not good, and it could even fry
51 one or both of the chips.
52
53 Unfortunately FTDI's stupid chip design does not allow the desired MPSSE mode
54 to be configured in the EEPROM so that it is there right from power-up. But
55 there is a workaround: if the EEPROM config is set up to put Channel A (the one
56 that will be wired for JTAG) into the rarely-used 245 FIFO mode instead of UART,
57 all 8 ADBUS pins (including ADBUS2 where TDO will be connected) will power up
58 as inputs with weak internal pull-ups (as long as the ACBUS2 control line is
59 left unconnected), which is much safer than what these pins do in the default
60 UART mode.
61
62 And if we need to program the EEPROM with a special custom config to change
63 Channel A from 232 UART to 245 FIFO, we can also assign a different USB VID:PID
64 at the same time. FTDI's default FT2232x ID of 0403:6010 works great when both
65 channels of the FT2232x device are used as UARTs - the Linux kernel recognizes
66 this USB ID, creates a pair of ttyUSB devices (one for each channel), and
67 everything Just Works. But what if Channel A is used for JTAG and is therefore
68 not a valid UART channel? If the default USB ID is left unchanged, what happens
69 is that a pair of ttyUSB devices still gets created, with the first out of the
70 pair being completely bogus and non-functional. And when you run OpenOCD, that
71 bogus Channel A ttyUSB device disappears, while the Channel B ttyUSB device
72 (which will actually work if Channel B is wired as a UART) remains, creating a
73 gap in ttyUSB numbers. If you have a ton of ttyUSB devices on your system and
74 are struggling to keep track of which is which, this behaviour certainly does
75 not help.
76
77 As it happens, our company Falconia Partners LLC has received a block of 8 PIDs
78 from FTDI, allocated out of FTDI's VID range - these PIDs have been officially
79 allocated by FTDI to our company for use in products based on FTDI chips. And
80 because we can spare one PID for a worthy cause, one of these PIDs (0403:7151)
81 is hereby being donated to the community for use on generic FT2232x boards in
82 the unbuffered JTAG adapter configuration.
83
84 Support for this 0403:7151 USB ID has been added to Linux ftdi_sio driver in
85 2020-09 with this commit:
86
87 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6cf87e5edd9944e1d3b6efd966ea401effc304ee
88
89 This commit is included in stable kernel versions 4.4.240, 4.9.240, 4.14.202,
90 4.19.152, 5.4.72, 5.8.16 and 5.9.1, and it will appear in mainline kernels from
91 5.10 onward. If your Linux kernel version (or rather ftdi_sio driver version
92 if it's a module) includes this commit, the ftdi_sio driver will create a
93 ttyUSB device for Channel B, allowing that channel to function as a UART if
94 desired, but Channel A will be left alone by the kernel driver, reserved for
95 userspace applications like OpenOCD. If your kernel/driver version does not
96 include the newly added commit, both FT2232x channels will be left alone by the
97 kernel driver, i.e., no ttyUSB devices will be created. If you are interested
98 only in JTAG and don't need an extra UART on Channel B, it should not matter
99 whether your ftdi_sio driver knows about the new custom USB ID or not - you
100 simply configure your OpenOCD in userspace to find your unbuffered and ad-hoc-
101 wired JTAG adapter at USB ID 0403:7151. If you do need the UART on Channel B
102 but your Linux kernel version does not include the recent addition, you will
103 need to manually apply the trivial patch from the commit linked above.
104
105 Choice of FT2232x breakout board
106 ================================
107
108 Here at FreeCalypso HQ we make very extensive use of FT2232C/D breakout boards
109 by PLDkit, and I officially recommend and endorse this vendor:
110
111 http://pldkit.com/other/ft2232d-module
112
113 These modules were originally made with FT2232D chips, then the vendor found a
114 stash of old but still good FT2232C chips, and some modules were made with these
115 FT2232C chips. Now it looks like the vendor has gone back to FT2232D - but this
116 distinction makes no difference for the present purpose.
117
118 These days FT2232H chips and FT2232H breakout boards are much more popular, but
119 I generally prefer FT2232C/D for classicness and simplicity. Additionally,
120 FTDI's AN_184 document lists I/O pin behaviour of various FTDI chips including
121 FT2232D and FT2232H; according to this document FT2232H I/O pins go through a
122 brief phase of acting as UART signals (including RTS output on ADBUS2) while
123 the EEPROM is being read, whereas FT2232D I/O pins are tristated during this
124 time. Thus I strongly recommend using an FT2232D breakout board.
125
126 Programming the EEPROM
127 ======================
128
129 The officially recommended FT2232D breakout boards from PLDkit have 93C46
130 EEPROMs on them, and the boards are shipped with blank EEPROMs. The blank
131 EEPROM state is perfectly good for operating the board as a dual UART, but our
132 JTAG application calls for custom EEPROM programming. A number of people in
133 the FOSS community have produced several different tools for programming FTDI
134 EEPROMs, and you could even use FTDI's official Winblows tools if you like, but
135 I am going to describe how to program the EEPROM using the tools which I
136 developed and which are used in production here at Falconia Partners LLC.
137
138 To compile my FTDI EEPROM tools, go into the fteeprom directory and run make
139 there; you will need to have libftdi (the classic one, not libftdi1) installed
140 on your system. If all you seek to do is to program this one EEPROM, you don't
141 need to install my tools system-wide - you can just run them from the directory
142 where they are compiled.
143
144 If you have the FT2232D board in its initial blank-EEPROM state plugged into
145 your system and you don't have any other FT2232x devices with 0403:6010 IDs,
146 you can program the EEPROM for JTAG as follows - run this pipeline from the top
147 directory of this code repository:
148
149 fteeprom/ftee-gen2232c eeproms/jtag-unbuf | fteeprom/fteeprom-prog i:0x0403:0x6010
150
151 Then unplug and replug the FT2232D board, and it should come back with the new
152 0403:7151 USB ID. If you wish to bring it back to its original blank-EEPROM
153 state, you can do so by erasing the EEPROM:
154
155 fteeprom-erase i:0x0403:0x7151
156
157 Wire connections
158 ================
159
160 The JTAG signal connections to ADBUS0 through ADBUS3 are fixed by FTDI, and if
161 you go against my advice and use FT2232H rather than FT2232C/D, then ADBUS7 is
162 also reserved for RTCK. The I/O pins available for reset and other sideband or
163 GPIO signals are ADBUS4 through ADBUS7 on FT2232C/D adapters, or ADBUS4 through
164 ADBUS6 and ACBUS5 through ACBUS7 on FT2232H. The other pins should be left
165 untouched to avoid problems with the 245 FIFO mode which is active in the time
166 window between power-up (USB plug-in) and running OpenOCD.