FreeCalypso > hg > freecalypso-hwlab

comparison doc/Unbuffered-FT2232x-JTAG @ 52:ace3ed1d5ddf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Unbuffered FT2232x JTAG article written
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 23 Apr 2019 01:22:41 +0000
parents
children 96232f00bc9c
comparison
equal deleted inserted replaced
51:311c800268b8 52:ace3ed1d5ddf
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 As of this writing, this 0403:7151 PID has not been submitted to Linux ftdi_sio
85 kernel maintainers yet, thus if you program it into your FT2232x EEPROM
86 following the instructions below, the kernel will leave that FT2232x device
87 completely alone. If you are interested only in JTAG and don't need an extra
88 UART on Channel B, this arrangement should be fully sufficient - you simply
89 configure your OpenOCD in userspace to find your unbuffered and ad-hoc-wired
90 JTAG adapter at that USB ID. And if you do need the UART on Channel B, you can
91 trivially patch your ftdi_sio.c kernel driver, adding the new ID to the table
92 with JTAG quirk (&ftdi_jtag_quirk) specified.
93
94 Choice of FT2232x breakout board
95 ================================
96
97 Here at FreeCalypso HQ we make very extensive use of FT2232C/D breakout boards
98 by PLDkit, and I officially recommend and endorse this vendor:
99
100 http://pldkit.com/other/ft2232d-module
101
102 These modules were originally made with FT2232D chips, then the vendor found a
103 stash of old but still good FT2232C chips, so apparently the current ones are
104 FT2232C, not D - but this distinction makes no difference for the present
105 purpose.
106
107 These days FT2232H chips and FT2232H breakout boards are much more popular, but
108 I generally prefer FT2232C/D for classicness and simplicity. Additionally,
109 FTDI's AN_184 document lists I/O pin behaviour of various FTDI chips including
110 FT2232D and FT2232H; according to this document FT2232H I/O pins go through a
111 brief phase of acting as UART signals (including RTS output on ADBUS2) while
112 the EEPROM is being read, whereas FT2232D I/O pins are tristated during this
113 time. Thus I strongly recommend using an FT2232D breakout board.
114
115 Programming the EEPROM
116 ======================
117
118 The officially recommended FT2232D breakout boards from PLDkit have 93C46
119 EEPROMs on them, and the boards are shipped with blank EEPROMs. The blank
120 EEPROM state is perfectly good for operating the board as a dual UART, but our
121 JTAG application calls for custom EEPROM programming. A number of people in
122 the FOSS community have produced several different tools for programming FTDI
123 EEPROMs, and you could even use FTDI's official Winblows tools if you like, but
124 I am going to describe how to program the EEPROM using the tools which I
125 developed and which are used in production here at Falconia Partners LLC.
126
127 To compile my FTDI EEPROM tools, go into the fteeprom directory and run make
128 there; you will need to have libftdi (the classic one, not libftdi1) installed
129 on your system. If all you seek to do is to program this one EEPROM, you don't
130 need to install my tools system-wide - you can just run them from the directory
131 where they are compiled.
132
133 If you have the FT2232D board in its initial blank-EEPROM state plugged into
134 your system and you don't have any other FT2232x devices with 0403:6010 IDs,
135 you can program the EEPROM for JTAG as follows - run this pipeline from the top
136 directory of this code repository:
137
138 fteeprom/ftee-gen2232c eeproms/jtag-unbuf | fteeprom/fteeprom-prog i:0x0403:0x6010
139
140 Then unplug and replug the FT2232D board, and it should come back with the new
141 0403:7151 USD ID. If you wish to bring it back to its original blank-EEPROM
142 state, you can do so by erasing the EEPROM:
143
144 fteeprom-erase i:0x0403:0x7151
145
146 Wire connections
147 ================
148
149 The JTAG signal connections to ADBUS0 through ADBUS3 are fixed by FTDI, and if
150 you go against my advice and use FT2232H rather than FT2232C/D, then ADBUS7 is
151 also reserved for RTCK. The I/O pins available for reset and other sideband or
152 GPIO signals are ADBUS4 through ADBUS7 on FT2232C/D adapters, or ADBUS4 through
153 ADBUS6 and ACBUS5 through ACBUS7 on FT2232H. The other pins should be left
154 untouched to avoid problems with the 245 FIFO mode which is active in the time
155 window being power-up (USB plug-in) and running OpenOCD.