Fix Luminary FT2232 layout docs/configs

Most of this patch updates documentation and comments for various
Luminary boards, supporting two bug fixes by helping to make sense
of the current mess:

 - Recent rev C lm3s811 eval boards didn't work.  They must use
   the ICDI layout, which sets up some signals that the older
   boards didn't need.  This is actually safe and appropriate
   for *all* recent boards ... so just make "luminary.cfg" use
   the ICDI layout.

 - "luminary-lm3s811.cfg", was previously unusable!  No VID/PID;
   and the wrong vendor string.  Make it work, but reserve it
   for older boards where the ICDI layout is wrong.

 - Default the LM3748 eval board to "luminary.cfg", like the
   other boards.  If someone uses an external JTAG adapter, all
   boards will use the same workaround (override that default).

The difference between the two FT2232 layouts is that eventually
the EVB layout will fail cleanly when asked to enable SWO trace,
but the ICDI layout will as cleanly be able to enable it.  Folk
using "luminary.cfg" with Rev B boards won't see anything going
wrong until SWO support is (someday) added.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

7 files changed, 67 insertions, 11 deletions

diff --git a/NEWS b/NEWS
index e3e813cb..ba7e0e60 100644
--- a/NEWS
+++ b/NEWS
@@ -52,6 +52,9 @@ Board, Target, and Interface Configuration Scripts:
 	ARM9
 		- ETM and ETB hookup for iMX2* targets
 	Add $HOME/.openocd to the search path.
+	Handle Rev C of LM3S811 eval boards.
+		- use "luminary-lm3s811.cfg" for older boards
+		- use "luminary.cfg" for RevC and newer
 
 Core Jim/TCL Scripting:
 	New 'usage' command to provide terse command help.
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 154ecbca..02caf5b1 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -288,10 +288,17 @@ chips are starting to become available in JTAG adapters.
 @* See: @url{http://www.oocdlink.com} By Joern Kaipf
 @item @b{signalyzer}
 @* See: @url{http://www.signalyzer.com}
-@item @b{evb_lm3s811}
-@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
-@item @b{luminary_icdi}
-@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
+@item @b{Stellaris Eval Boards}
+@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
+bundle FT2232-based JTAG and SWD support, which can be used to debug
+the Stellaris chips.  Using separate JTAG adapters is optional.
+These boards can also be used as JTAG adapters to other target boards,
+disabling the Stellaris chip.
+@item @b{Luminary ICDI}
+@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
+Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
+Evaluation Kits.  Like the non-detachable FT2232 support on the other
+Stellaris eval boards, they can be used to debug other target boards.
 @item @b{olimex-jtag}
 @* See: @url{http://www.olimex.com}
 @item @b{flyswatter}
@@ -1962,7 +1969,12 @@ Currently valid layout @var{name} values include:
 @item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
 either for the local Cortex-M3 (SRST only)
 or in a passthrough mode (neither SRST nor TRST)
-@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
+This layout can not support the SWO trace mechanism, and should be
+used only for older boards (before rev C).
+@item @b{luminary_icdi} This layout should be used with most Luminary
+eval boards, including Rev C LM3S811 eval boards and the eponymous
+ICDI boards, to debug either the local Cortex-M3 or in passthrough mode
+to debug some other target.  It can support the SWO trace mechanism.
 @item @b{flyswatter} Tin Can Tools Flyswatter
 @item @b{icebear} ICEbear JTAG adapter from Section 5
 @item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
diff --git a/src/jtag/drivers/ft2232.c b/src/jtag/drivers/ft2232.c
index 831a5dca..06fc2523 100644
--- a/src/jtag/drivers/ft2232.c
+++ b/src/jtag/drivers/ft2232.c
@@ -2182,6 +2182,11 @@ static int usbjtag_init(void)
 	}
 	else if (strcmp(ft2232_layout, "evb_lm3s811") == 0)
 	{
+		/* There are multiple revisions of LM3S811 eval boards:
+		 * - Rev B (and older?) boards have no SWO trace support.
+		 * - Rev C boards add ADBUS_6 DBG_ENn and BDBUS_4 SWO_EN;
+		 *   they should use the "luminary_icdi" layout instead.
+		 */
 		nTRST = 0x0;
 		nTRSTnOE = 0x00;
 		nSRST = 0x20;
@@ -2191,6 +2196,9 @@ static int usbjtag_init(void)
 	}
 	else if (strcmp(ft2232_layout, "luminary_icdi") == 0)
 	{
+		/* Most Luminary eval boards support SWO trace output,
+		 * and should use this "luminary_icdi" layout.
+		 */
 		nTRST = 0x0;
 		nTRSTnOE = 0x00;
 		nSRST = 0x20;
diff --git a/tcl/board/ek-lm3s3748.cfg b/tcl/board/ek-lm3s3748.cfg
index 950e5119..7613a0ad 100644
--- a/tcl/board/ek-lm3s3748.cfg
+++ b/tcl/board/ek-lm3s3748.cfg
@@ -1,8 +1,8 @@
 # Stellaris lm3s3748 Evaluation Kit
 #  http://www.luminarymicro.com/products/lm3s3748_usb_h_d_evaluation_kits.html
 
-# NOTE:  to use the on-board FT2232 JTAG interface:
-#  source [find interface/luminary.cfg]
+# NOTE:  using the on-board FT2232 JTAG/SWD/SWO interface is optional!
+source [find interface/luminary.cfg]
 
 source [find target/stellaris.cfg]
 
diff --git a/tcl/interface/luminary-icdi.cfg b/tcl/interface/luminary-icdi.cfg
index 04330a16..ec772562 100644
--- a/tcl/interface/luminary-icdi.cfg
+++ b/tcl/interface/luminary-icdi.cfg
@@ -2,6 +2,11 @@
 # Luminary Micro Stellaris LM3S9B9x Evaluation Kits
 # In-Circuit Debug Interface (ICDI) Board
 #
+# This is a discrete FT2232 based debug board which supports ARM's
+# JTAG/SWD connectors in both backwards-compatible 20-pin format and
+# in the new-style compact 10-pin.  There's also an 8-pin connector
+# with serial port support.  It's included with LM3S9B9x eval boards.
+#
 # http://www.luminarymicro.com/products/ek-lm3s9b90.html
 # http://www.luminarymicro.com/products/ek-lm3s9b92.html
 #
diff --git a/tcl/interface/luminary-lm3s811.cfg b/tcl/interface/luminary-lm3s811.cfg
index 3d4b9760..4c1accde 100644
--- a/tcl/interface/luminary-lm3s811.cfg
+++ b/tcl/interface/luminary-lm3s811.cfg
@@ -3,8 +3,16 @@
 #
 # http://www.luminarymicro.com/products/stellaris_811_evaluation_kits.html
 #
+# NOTE:  this is only for boards *before* Rev C, which adds support
+# for SWO tracing with ADBUS_6 DBG_ENn and BDBUS_4 SWO_EN signals.
+# The "evb_lm3s811" layout doesn't set up those signals.
+#
+# Rev C boards work more like the other Stellaris eval boards.  They
+# need to use the "luminary_icdi" layout to work correctly.
+#
 
 interface ft2232
-ft2232_device_desc "LM3S811 Evaluation Board"
+ft2232_device_desc "Stellaris Evaluation Board"
 ft2232_layout evb_lm3s811
+ft2232_vid_pid 0x0403 0xbcd9
 
diff --git a/tcl/interface/luminary.cfg b/tcl/interface/luminary.cfg
index c86dbb6e..e94e5149 100644
--- a/tcl/interface/luminary.cfg
+++ b/tcl/interface/luminary.cfg
@@ -1,11 +1,31 @@
 #
-# Luminary Micro Stellaris LM3S811 Evaluation Kit
+# Luminary Micro Stellaris Evaluation Kits
 #
-# http://www.luminarymicro.com/products/stellaris_811_evaluation_kits.html
+# http://www.luminarymicro.com/products/evaluation_kits.html
+#
+# There are a number of evaluation kits for Stellaris Cortex-M3 chips.
+# Currently they all bundle FT2232 based debug support.  When that is
+# used (instead of an external adapter), use this config file in one
+# of these two modes:
+#
+# - Eval board debug ... debug of the Stellaris chip via port A.
+#
+# - Other board debug ... same thing, but the board acts as a debug
+#   adapter for another board (using a standard ARM JTAG connector).
+#   The Stellaris chip stays in reset.
+#
+# Those support both JTAG and SWD.  SWD is an ARM-only two-wire debug
+# protocol; in 2009, OpenOCD does not support SWD.
+#
+# Port B of the FT2232 chip is normally used as a serial link to the
+# Stellaris chip.  On most boards (but not older LM3S811 eval boards),
+# when SWD is used Port B may instead be used to read low-bandwidth
+# "SWO trace" data, including so-called "printf style" output from
+# firmware via the ITM module as well as profile data.
 #
 
 interface ft2232
 ft2232_device_desc "Stellaris Evaluation Board"
-ft2232_layout evb_lm3s811
+ft2232_layout luminary_icdi
 ft2232_vid_pid 0x0403 0xbcd9