David Brownell <david-b@pacbell.net>:

Distributing FTDI's "ftd2xx" library with OpenOCD violates the
OpenOCD license (GNU GPLv2 with no exceptions).

Make that clear where that build option is presented, and don't
describe the FTDI libraries as an option for any packager.  (It's
fine for personal use, of course.)

Plus some related clarifications:  libftdi version 0.16 for the
new FT2232H chips (for RTCK and high speed USB); the Amontec
drivers are just ftd2xx variants.


git-svn-id: svn://svn.berlios.de/openocd/trunk@2248 b42882b7-edfa-0310-969c-e2dbd0fdcd60

1 files changed, 23 insertions, 28 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 7f73a4c..3a396b1 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -238,27 +238,11 @@ That said, the OpenOCD developers would also like you to follow a few
 suggestions:
 
 @enumerate
-@item @b{Send patches, including config files, upstream.}
-@item @b{Always build with printer ports enabled.}
-@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
+@item Send patches, including config files, upstream.
+@item Always build with printer ports enabled.
+@item Use libftdi + libusb for FT2232 support.
 @end enumerate
 
-@itemize @bullet
-@item @b{Why YES to LIBFTDI + LIBUSB?}
-@itemize @bullet
-@item @b{LESS} work - libusb perhaps already there
-@item @b{LESS} work - identical code, multiple platforms
-@item @b{MORE} dongles are supported
-@item @b{MORE} platforms are supported
-@item @b{MORE} complete solution
-@end itemize
-@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
-@itemize @bullet
-@item @b{LESS} speed - some say it is slower
-@item @b{LESS} complex to distribute (external dependencies)
-@end itemize
-@end itemize
-
 @section Building From Source
 
 You can download the current SVN version with an SVN client of your choice from the
@@ -297,16 +281,21 @@ a FTDI FT2232 based interface:
 
 @itemize @bullet
 @item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
-@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
-@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
-homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
+@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}),
+or the Amontec version (from @uref{http://www.amontec.com}),
+for easier support of JTAGkey's vendor and product IDs.
 @end itemize
 
 libftdi is supported under Windows. Do not use versions earlier than 0.14.
+To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps),
+you need libftdi version 0.16 or newer.
 
-In general, the D2XX driver provides superior performance (several times as fast),
-but has the draw-back of being binary-only - though that isn't that bad, as it isn't
-a kernel module, only a user space library.
+Some people say that FTDI's libftd2xx code provides better performance.
+However, it is binary-only, while OpenOCD is licenced according
+to GNU GPLv2 without any exceptions.
+That means that @emph{distributing} copies of OpenOCD built with
+the FTDI code would violate the OpenOCD licensing terms.
+You may, however, build such copies for personal use.
 
 To build OpenOCD (on both Linux and Cygwin), use the following commands:
 
@@ -354,9 +343,12 @@ should be included (among other things):
 @item
 @option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
 @item
-@option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
+@option{--enable-ft2232_ftd2xx} - Support FT2232-family chips using
+the closed-source library from FTDICHIP.COM
+(result not for re-distribution).
 @item
-@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
+@option{--enable-ft2232_libftdi} - Support FT2232-family chips using
+a GPL'd ft2232 support library (result OK for re-distribution).
 @item
 @option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
 give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@@ -399,7 +391,10 @@ use both the @option{--enable-parport} AND the @option{--enable-parport_giveio}
 
 There are 2 methods of using the FTD2232, either (1) using the
 FTDICHIP.COM closed source driver, or (2) the open (and free) driver
-libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
+libftdi. Some claim the (closed) FTDICHIP.COM solution is faster,
+which is the motivation for supporting it even though its licensing
+restricts it to non-redistributable OpenOCD binaries, and it is
+not available for all operating systems used with OpenOCD.
 
 The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
 TAR.GZ file. You must unpack them ``some where'' convient. As of this