FreeCalypso > hg > freecalypso-hwlab

comparison doc/Unbuffered-FT2232x-JTAG @ 174:4f5abad5dd40

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Unbuffered-FT2232x-JTAG: update for fc-usbser-tools
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 11 Sep 2023 07:23:18 +0000
parents bbeec8f293dc
children
comparison
equal deleted inserted replaced
173:df4bf4e06221 174:4f5abad5dd40
1 How to make a safe JTAG adapter out of a generic unbuffered FT2232x board 1 How to make a safe JTAG adapter out of a generic unbuffered FT2232x board
2 ========================================================================= 2 =========================================================================
3
4 [This guide was originally written in 2019; it has been updated slightly for
5 the move of FTDI EEPROM utilities to fc-usbser-tools, plus other minor updates
6 for the situation in 2023, but the principal ideas are all from 2019.]
3 7
4 Among the FOSS community of tinkerers who use OpenOCD to operate on the JTAG 8 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 9 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 10 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 11 chip, most commonly one of FT2232x variants. However, a major distinction needs
11 15
12 In an ideal world, using a purpose-made buffered JTAG adapter (one that has a 16 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) 17 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 18 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 19 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 20 adapters, and when I last looked in 2019, I was NOT able to find any high-
17 which can be bought in the present and which comes with published schematics. 21 quality buffered JTAG adapter which could be readily bought and which comes
18 (There is one very well-known vendor of "community" JTAG adapters who refuses 22 with published schematics.
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 23
27 Given the current sorry state of availability of buffered JTAG adapters, I have 24 Given the sorry state of availability of buffered JTAG adapters, I gave more
28 given more thought to the unbuffered option, and I found what appears to be a 25 thought to the unbuffered option, and I found what appears to be a way to make
29 way to make them safe - but my method requires programming the EEPROM on the 26 them safe - but my method requires programming the EEPROM on the FT2232x board
30 FT2232x board with a special custom configuration, and in this article I am 27 with a special custom configuration, and in this article I am going to provide
31 going to provide the full details and instructions. 28 the full details and instructions.
32 29
33 To begin with, an unbuffered JTAG adapter (one in which the target JTAG signals 30 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 31 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 32 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 33 a slightly lower but still fully 3.3V-compatible logic voltage level like the
84 Support for this 0403:7151 USB ID has been added to Linux ftdi_sio driver in 81 Support for this 0403:7151 USB ID has been added to Linux ftdi_sio driver in
85 2020-09 with this commit: 82 2020-09 with this commit:
86 83
87 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6cf87e5edd9944e1d3b6efd966ea401effc304ee 84 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6cf87e5edd9944e1d3b6efd966ea401effc304ee
88 85
89 This commit is included in stable kernel versions 4.4.240, 4.9.240, 4.14.202, 86 This commit is included in mainline kernel versions from 5.10 onward, and in
90 4.19.152, 5.4.72, 5.8.16 and 5.9.1, and it will appear in mainline kernels from 87 stable kernel versions 4.4.240, 4.9.240, 4.14.202, 4.19.152, 5.4.72, 5.8.16 and
91 5.10 onward. If your Linux kernel version (or rather ftdi_sio driver version 88 5.9.1. If your Linux kernel version (or rather ftdi_sio driver version if it's
92 if it's a module) includes this commit, the ftdi_sio driver will create a 89 a module) includes this commit, the ftdi_sio driver will create a ttyUSB device
93 ttyUSB device for Channel B, allowing that channel to function as a UART if 90 for Channel B, allowing that channel to function as a UART if desired, but
94 desired, but Channel A will be left alone by the kernel driver, reserved for 91 Channel A will be left alone by the kernel driver, reserved for userspace
95 userspace applications like OpenOCD. If your kernel/driver version does not 92 applications like OpenOCD. If your kernel/driver version (older than late 2020)
96 include the newly added commit, both FT2232x channels will be left alone by the 93 does not include the commit in question, both FT2232x channels will be left
97 kernel driver, i.e., no ttyUSB devices will be created. If you are interested 94 alone by the kernel driver, i.e., no ttyUSB devices will be created. If you are
98 only in JTAG and don't need an extra UART on Channel B, it should not matter 95 interested only in JTAG and don't need an extra UART on Channel B, it should not
99 whether your ftdi_sio driver knows about the new custom USB ID or not - you 96 matter whether your ftdi_sio driver knows about the new custom USB ID or not -
100 simply configure your OpenOCD in userspace to find your unbuffered and ad-hoc- 97 you simply configure your OpenOCD in userspace to find your unbuffered and
101 wired JTAG adapter at USB ID 0403:7151. If you do need the UART on Channel B 98 ad-hoc-wired JTAG adapter at USB ID 0403:7151. If you do need the UART on
102 but your Linux kernel version does not include the recent addition, you will 99 Channel B but your Linux kernel version is old, you will need to manually apply
103 need to manually apply the trivial patch from the commit linked above. 100 the trivial patch from the commit linked above.
104 101
105 Choice of FT2232x breakout board 102 Choice of FT2232x breakout board
106 ================================ 103 ================================
107 104
108 Here at FreeCalypso HQ we make very extensive use of FT2232C/D breakout boards 105 In earlier years we made heavy use of generic FT2232D breakout boards made by
109 by PLDkit, and I officially recommend and endorse this vendor: 106 PLDkit OU in Estonia. We are not sure if that original company still makes
107 them or not, but the person behind that company name did eventually sell us
108 their Gerber files, and we have published them here:
110 109
111 http://pldkit.com/other/ft2232d-module 110 ftp://ftp.freecalypso.org/pub/USB/FTDI/
111 or
112 https://www.freecalypso.org/pub/USB/FTDI/
112 113
113 These modules were originally made with FT2232D chips, then the vendor found a 114 Given that we have a stash of FT2232D chips and given that we still have use
114 stash of old but still good FT2232C chips, and some modules were made with these 115 cases for these generic breakout boards, we have a tentative plan to produce
115 FT2232C chips. Now it looks like the vendor has gone back to FT2232D - but this 116 our own Falconia-branded version of the same adapter/breakout board.
116 distinction makes no difference for the present purpose.
117 117
118 These days FT2232H chips and FT2232H breakout boards are much more popular, but 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, 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 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 121 FT2232D and FT2232H; according to this document FT2232H I/O pins go through a
124 time. Thus I strongly recommend using an FT2232D breakout board. 124 time. Thus I strongly recommend using an FT2232D breakout board.
125 125
126 Programming the EEPROM 126 Programming the EEPROM
127 ====================== 127 ======================
128 128
129 The officially recommended FT2232D breakout boards from PLDkit have 93C46 129 The boards we used to buy from PLDkit (FT2232D breakout) have 93C46 EEPROMs on
130 EEPROMs on them, and the boards are shipped with blank EEPROMs. The blank 130 them, and the boards were shipped with blank EEPROMs. The blank EEPROM state
131 EEPROM state is perfectly good for operating the board as a dual UART, but our 131 is perfectly good for operating the board as a dual UART, but our JTAG
132 JTAG application calls for custom EEPROM programming. A number of people in 132 application calls for custom EEPROM programming. A number of people in the
133 the FOSS community have produced several different tools for programming FTDI 133 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 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 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. 136 developed and which are used in production here at FreeCalypso HQ.
137 137
138 To compile my FTDI EEPROM tools, go into the fteeprom directory and run make 138 FreeCalypso FTDI EEPROM tools reside in this Hg repository:
139 there; you will need to have libftdi (the classic one, not libftdi1) installed 139
140 on your system. If all you seek to do is to program this one EEPROM, you don't 140 https://www.freecalypso.org/hg/fc-usbser-tools/
141 need to install my tools system-wide - you can just run them from the directory 141
142 where they are compiled. 142 You will need to compile and install these tools, then continue.
143 143
144 If you have the FT2232D board in its initial blank-EEPROM state plugged into 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, 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 146 you can program the EEPROM for JTAG as follows (the command is a shell
147 directory of this code repository: 147 pipeline):
148 148
149 fteeprom/ftee-gen2232c eeproms/jtag-unbuf | fteeprom/fteeprom-prog i:0x0403:0x6010 149 ftee-gen2232c jtag-unbuf | fteeprom-prog i:0x0403:0x6010
150 150
151 Then unplug and replug the FT2232D board, and it should come back with the new 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 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: 153 state, you can do so by erasing the EEPROM:
154 154