From e1258c703bf9e6a0868f4d9e939c4be77567c53e Mon Sep 17 00:00:00 2001 From: David Brownell Date: Sun, 3 Jan 2010 14:54:52 -0800 Subject: [PATCH] JTAG/drivers: ft2232 docs Add doxyegen description for this driver. Correct the helptext (configures *or* displays based on #params), and usage (use the same BNF as the User's Guide). Remove superfluous #include Signed-off-by: David Brownell --- src/jtag/drivers/ft2232.c | 40 ++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/src/jtag/drivers/ft2232.c b/src/jtag/drivers/ft2232.c index a3ac142b..e9eba541 100644 --- a/src/jtag/drivers/ft2232.c +++ b/src/jtag/drivers/ft2232.c @@ -27,13 +27,40 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ -/* This code uses information contained in the MPSSE specification which was +/** + * @file + * JTAG adapters based on the FT2232 full and high speed USB parts are + * popular low cost JTAG debug solutions. Many FT2232 based JTAG adapters + * are discrete, but development boards may integrate them as alternatives + * to more capable (and expensive) third party JTAG pods. Since JTAG uses + * only one of the two parts on these devices, on integrated boards the + * second port often serves as a USB-to-serial adapter for the target's + * console UART even when the JTAG port is not in use. (Systems which + * support ARM's SWD in addition to JTAG, or instead of it, may use that + * second port for reading SWV trace data.) + * + * FT2232 based JTAG adapters are "dumb" not "smart", because most JTAG + * request/response interactions involve round trips over the USB link. + * A "smart" JTAG adapter has intelligence close to the scan chain, so it + * can for example poll quickly for a status change (usually taking on the + * order of microseconds not milliseconds) before beginning a queued + * transaction which require the previous one to have completed. + * + * There are dozens of adapters of this type, differing in details which + * this driver needs to understand. Those "layout" details are required + * as part of FT2232 driver configuration. + * + * This code uses information contained in the MPSSE specification which was * found here: * http://www.ftdichip.com/Documents/AppNotes/AN2232C-01_MPSSE_Cmnd.pdf * Hereafter this is called the "MPSSE Spec". * * The datasheet for the ftdichip.com's FT2232D part is here: * http://www.ftdichip.com/Documents/DataSheets/DS_FT2232D.pdf + * + * Also note the issue with code 0x4b (clock data to TMS) noted in + * http://developer.intra2net.com/mailarchive/html/libftdi/2009/msg00292.html + * which can affect longer JTAG state paths. */ #ifdef HAVE_CONFIG_H @@ -42,7 +69,6 @@ /* project specific includes */ #include -#include #include #if IS_CYGWIN == 1 @@ -3983,14 +4009,14 @@ static const struct command_registration ft2232_command_handlers[] = { .handler = &ft2232_handle_device_desc_command, .mode = COMMAND_CONFIG, .help = "set the USB device description of the FTDI FT2232 device", - .usage = "", + .usage = "description_string", }, { .name = "ft2232_serial", .handler = &ft2232_handle_serial_command, .mode = COMMAND_CONFIG, .help = "set the serial number of the FTDI FT2232 device", - .usage = "", + .usage = "serial_string", }, { .name = "ft2232_layout", @@ -3998,21 +4024,21 @@ static const struct command_registration ft2232_command_handlers[] = { .mode = COMMAND_CONFIG, .help = "set the layout of the FT2232 GPIO signals used " "to control output-enables and reset signals", - .usage = "", + .usage = "layout_name", }, { .name = "ft2232_vid_pid", .handler = &ft2232_handle_vid_pid_command, .mode = COMMAND_CONFIG, .help = "the vendor ID and product ID of the FTDI FT2232 device", - .usage = " [...]", + .usage = "(vid pid)* ", }, { .name = "ft2232_latency", .handler = &ft2232_handle_latency_command, .mode = COMMAND_CONFIG, .help = "set the FT2232 latency timer to a new value", - .usage = " [...]", + .usage = "value", }, COMMAND_REGISTRATION_DONE }; -- 2.39.5