FreeCalypso > hg > freecalypso-hwlab
view doc/Unbuffered-FT2232x-JTAG @ 137:c331560c15a4
fc-uicc-tool: dir command implemented
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 04 Feb 2021 04:27:09 +0000 |
parents | bbeec8f293dc |
children | 4f5abad5dd40 |
line wrap: on
line source
How to make a safe JTAG adapter out of a generic unbuffered FT2232x board ========================================================================= Among the FOSS community of tinkerers who use OpenOCD to operate on the JTAG interfaces of various hardware targets, one of the most common JTAG adapter choices (if not the most common) is to use some adapter gadget based on an FTDI chip, most commonly one of FT2232x variants. However, a major distinction needs to be drawn between specialized purpose-made JTAG adapter products which just happen to use an FT2232x chip internally, versus generic FT2232x breakout boards which the user wires up for JTAG on his or her own. In an ideal world, using a purpose-made buffered JTAG adapter (one that has a buffer inserted between FT2232x I/O pins and the target connection interface) would be strongly preferable for a whole host of reasons. However, to this author's disappointment, there are very few community vendors who make such adapters, and I was NOT able to find any high-quality buffered JTAG adapter which can be bought in the present and which comes with published schematics. (There is one very well-known vendor of "community" JTAG adapters who refuses to publish schematics for their current model; they have an older model for which they did publish schematics, but it is discontinued and they are not interested in bringing it back into production or handing the complete design over to the community - probably because it would then compete with their current sans-schematics product! Selling JTAG adapters to the community while keeping their schematics secret is just assinine, and I refuse to give my business to such vendors.) Given the current sorry state of availability of buffered JTAG adapters, I have given more thought to the unbuffered option, and I found what appears to be a way to make them safe - but my method requires programming the EEPROM on the FT2232x board with a special custom configuration, and in this article I am going to provide the full details and instructions. To begin with, an unbuffered JTAG adapter (one in which the target JTAG signals are connected directly to FT2232x I/O pins without any buffer in between) can work only with targets that operate their JTAG interface at 3.3 V, or perhaps a slightly lower but still fully 3.3V-compatible logic voltage level like the 2.8 V I/O on Calypso GSM baseband processors. An unbuffered adapter CANNOT work with, say, a 1.8 V JTAG interface - but as long as your target runs at 3.3 or 2.8 V, then we can continue. The next big problem with unbuffered FT2232x adapters is that if you don't put a special configuration in the EEPROM (or if your FT2232x board omits the EEPROM altogether), the channel which you are going to wire up for JTAG (can only be Channel A on FT2232C/D, can be either channel on FT2232H) is going to come up in FTDI's default UART mode on power-up, and it is going to stay in that mode until and unless you run OpenOCD, which will then switch it into MPSSE mode for JTAG. Why is it a problem? Answer: you need to connect the TDO line from the target to the FT2232x chip's ADBUS2 pin for JTAG to work via MPSSE, but in the power-up default UART mode this ADBUS2 pin is the RTS output. FT2232x RTS output fighting with the target's TDO output - not good, and it could even fry one or both of the chips. Unfortunately FTDI's stupid chip design does not allow the desired MPSSE mode to be configured in the EEPROM so that it is there right from power-up. But there is a workaround: if the EEPROM config is set up to put Channel A (the one that will be wired for JTAG) into the rarely-used 245 FIFO mode instead of UART, all 8 ADBUS pins (including ADBUS2 where TDO will be connected) will power up as inputs with weak internal pull-ups (as long as the ACBUS2 control line is left unconnected), which is much safer than what these pins do in the default UART mode. And if we need to program the EEPROM with a special custom config to change Channel A from 232 UART to 245 FIFO, we can also assign a different USB VID:PID at the same time. FTDI's default FT2232x ID of 0403:6010 works great when both channels of the FT2232x device are used as UARTs - the Linux kernel recognizes this USB ID, creates a pair of ttyUSB devices (one for each channel), and everything Just Works. But what if Channel A is used for JTAG and is therefore not a valid UART channel? If the default USB ID is left unchanged, what happens is that a pair of ttyUSB devices still gets created, with the first out of the pair being completely bogus and non-functional. And when you run OpenOCD, that bogus Channel A ttyUSB device disappears, while the Channel B ttyUSB device (which will actually work if Channel B is wired as a UART) remains, creating a gap in ttyUSB numbers. If you have a ton of ttyUSB devices on your system and are struggling to keep track of which is which, this behaviour certainly does not help. As it happens, our company Falconia Partners LLC has received a block of 8 PIDs from FTDI, allocated out of FTDI's VID range - these PIDs have been officially allocated by FTDI to our company for use in products based on FTDI chips. And because we can spare one PID for a worthy cause, one of these PIDs (0403:7151) is hereby being donated to the community for use on generic FT2232x boards in the unbuffered JTAG adapter configuration. Support for this 0403:7151 USB ID has been added to Linux ftdi_sio driver in 2020-09 with this commit: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6cf87e5edd9944e1d3b6efd966ea401effc304ee This commit is included in stable kernel versions 4.4.240, 4.9.240, 4.14.202, 4.19.152, 5.4.72, 5.8.16 and 5.9.1, and it will appear in mainline kernels from 5.10 onward. If your Linux kernel version (or rather ftdi_sio driver version if it's a module) includes this commit, the ftdi_sio driver will create a ttyUSB device for Channel B, allowing that channel to function as a UART if desired, but Channel A will be left alone by the kernel driver, reserved for userspace applications like OpenOCD. If your kernel/driver version does not include the newly added commit, both FT2232x channels will be left alone by the kernel driver, i.e., no ttyUSB devices will be created. If you are interested only in JTAG and don't need an extra UART on Channel B, it should not matter whether your ftdi_sio driver knows about the new custom USB ID or not - you simply configure your OpenOCD in userspace to find your unbuffered and ad-hoc- wired JTAG adapter at USB ID 0403:7151. If you do need the UART on Channel B but your Linux kernel version does not include the recent addition, you will need to manually apply the trivial patch from the commit linked above. Choice of FT2232x breakout board ================================ Here at FreeCalypso HQ we make very extensive use of FT2232C/D breakout boards by PLDkit, and I officially recommend and endorse this vendor: http://pldkit.com/other/ft2232d-module These modules were originally made with FT2232D chips, then the vendor found a stash of old but still good FT2232C chips, and some modules were made with these FT2232C chips. Now it looks like the vendor has gone back to FT2232D - but this distinction makes no difference for the present purpose. These days FT2232H chips and FT2232H breakout boards are much more popular, but I generally prefer FT2232C/D for classicness and simplicity. Additionally, FTDI's AN_184 document lists I/O pin behaviour of various FTDI chips including FT2232D and FT2232H; according to this document FT2232H I/O pins go through a brief phase of acting as UART signals (including RTS output on ADBUS2) while the EEPROM is being read, whereas FT2232D I/O pins are tristated during this time. Thus I strongly recommend using an FT2232D breakout board. Programming the EEPROM ====================== The officially recommended FT2232D breakout boards from PLDkit have 93C46 EEPROMs on them, and the boards are shipped with blank EEPROMs. The blank EEPROM state is perfectly good for operating the board as a dual UART, but our JTAG application calls for custom EEPROM programming. A number of people in the FOSS community have produced several different tools for programming FTDI EEPROMs, and you could even use FTDI's official Winblows tools if you like, but I am going to describe how to program the EEPROM using the tools which I developed and which are used in production here at Falconia Partners LLC. To compile my FTDI EEPROM tools, go into the fteeprom directory and run make there; you will need to have libftdi (the classic one, not libftdi1) installed on your system. If all you seek to do is to program this one EEPROM, you don't need to install my tools system-wide - you can just run them from the directory where they are compiled. If you have the FT2232D board in its initial blank-EEPROM state plugged into your system and you don't have any other FT2232x devices with 0403:6010 IDs, you can program the EEPROM for JTAG as follows - run this pipeline from the top directory of this code repository: fteeprom/ftee-gen2232c eeproms/jtag-unbuf | fteeprom/fteeprom-prog i:0x0403:0x6010 Then unplug and replug the FT2232D board, and it should come back with the new 0403:7151 USB ID. If you wish to bring it back to its original blank-EEPROM state, you can do so by erasing the EEPROM: fteeprom-erase i:0x0403:0x7151 Wire connections ================ The JTAG signal connections to ADBUS0 through ADBUS3 are fixed by FTDI, and if you go against my advice and use FT2232H rather than FT2232C/D, then ADBUS7 is also reserved for RTCK. The I/O pins available for reset and other sideband or GPIO signals are ADBUS4 through ADBUS7 on FT2232C/D adapters, or ADBUS4 through ADBUS6 and ACBUS5 through ACBUS7 on FT2232H. The other pins should be left untouched to avoid problems with the 245 FIFO mode which is active in the time window between power-up (USB plug-in) and running OpenOCD.