Build Permutations with ftd2xx and libftdi addressed. Also added a new se of regressi...

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index adc8a30cc6df4e378731f7bd66204f59a6d9e5c5..a26f9ed28f8520ded0f682b9a45d5318fd80557a 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -127,11 +127,13 @@ The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}
 @chapter Building
 @cindex building OpenOCD
 
+@section Pre-Built Tools
 If you are interested in getting actual work done rather than building
 OpenOCD, then check if your interface supplier provides binaries for
 you. Chances are that that binary is from some SVN version that is more
 stable than SVN trunk where bleeding edge development takes place.
 
+@section Building From Source
 
 You can download the current SVN version with SVN client of your choice from the
 following repositories:
@@ -166,8 +168,7 @@ a FTDI FT2232 based interface:
 homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID. 
 @end itemize
 
-libftdi is supported under windows. Versions earlier than 0.13 will require patching.
-see contrib/libftdi for more details.
+libftdi is supported under windows. Do not use versions earlier then 0.14.
 
 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
@@ -179,35 +180,37 @@ To build OpenOCD (on both Linux and Cygwin), use the following commands:
 @end example
 Bootstrap generates the configure script, and prepares building on your system.
 @example
- ./configure 
+ ./configure [options, see below]
 @end example
 Configure generates the Makefiles used to build OpenOCD.
 @example
  make 
+ make install
 @end example
-Make builds OpenOCD, and places the final executable in ./src/.
+Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
 
 The configure script takes several options, specifying which JTAG interfaces
 should be included:
 
 @itemize @bullet
 @item
-@option{--enable-parport}
+@option{--enable-parport} - Bit bang pc printer ports.
 @item
-@option{--enable-parport_ppdev}
+@option{--enable-parport_ppdev} - Parallel Port [see below]
 @item
-@option{--enable-parport_giveio}
+@option{--enable-parport_giveio} - Parallel Port [see below]
 @item
-@option{--enable-amtjtagaccel}
+@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
 @item
-@option{--enable-ft2232_ftd2xx}
-@footnote{Using the latest D2XX drivers from FTDI and following their installation
-instructions, I had to use @option{--enable-ft2232_libftd2xx} for OpenOCD to
-build properly.}
+@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
 @item
-@option{--enable-ft2232_libftdi}
+@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
 @item
-@option{--with-ftd2xx=/path/to/d2xx/}
+@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
+@item
+@option{--with-ftd2xx-linux-tardir=PATH} - Linux only equal of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
+@item
+@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static, specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. Shared is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
 @item
 @option{--enable-gw16012}
 @item
@@ -217,21 +220,72 @@ build properly.}
 @item
 @option{--enable-presto_ftd2xx}
 @item
-@option{--enable-jlink}
+@option{--enable-jlink} - From SEGGER
+@item
+@option{--enable-rlink} - Raisonance.com dongle.
 @end itemize
 
+@section Parallel Port Dongles
+
 If you want to access the parallel port using the PPDEV interface you have to specify
 both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
 the @option{--enable-parport_ppdev} option actually is an option to the parport driver
 (see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
 
-Cygwin users have to specify the location of the FTDI D2XX package. This should be an
-absolute path containing no spaces.
+@section FT2232C Based USB Dongles 
+
+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.
+
+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
+writing (12/26/2008) FTDICHIP does not supply means to install these
+files ``in an appropriate place'' As a result, there are two
+``./configure'' options that help. 
+
+Below is an example build process:
+
+1) Check out the latest version of ``openocd'' from SVN.
+
+2) Download & Unpack either the Windows or Linux FTD2xx Drivers
+    (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
+
+@example
+   /home/duane/ftd2xx.win32    => the Cygwin/Win32 ZIP file contents.
+   /home/duane/libftd2xx0.4.16 => the Linux TAR file contents.
+@end example
+
+3) Configure with these options:
+
+@example
+Cygwin FTCICHIP solution
+   ./configure --prefix=/home/duane/mytools \ 
+                  --enable-ft2232_ftd2xx \
+                  --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
+
+Linux FTDICHIP solution
+   ./configure --prefix=/home/duane/mytools \
+                  --enable-ft2232_ftd2xx \
+                  --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
+
+Cygwin/Linux LIBFTDI solution
+    Assumes: 
+    1a) For Windows: The windows port of LIBUSB is in place.
+    1b) For Linux: libusb has been built and is inplace.
+
+    2) And libftdi has been built and installed
+    Note: libftdi - relies upon libusb.
+
+    ./configure --prefix=/home/duane/mytools \
+                   --enable-ft2232_libftdi
+       
+@end example
 
-Linux users should copy the various parts of the D2XX package to the appropriate
-locations, i.e. /usr/include, /usr/lib. 
+4) Then just type ``make'', and perhaps ``make install''.
 
-Miscellaneous configure options
+
+@section Miscellaneous configure options
 
 @itemize @bullet
 @item
@@ -322,6 +376,18 @@ AT91SAM764 internally.
 @* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
 @end itemize
 
+@section USB RLINK based
+Raisonance has an adapter called @b{RLink}.  It exists in a stripped-down form on the STM32 Primer, permanently attached to the JTAG lines.  It also exists on the STM32 Primer2, but that is wired for SWD and not JTAG, thus not supported.
+
+@itemize @bullet
+@item @b{Raisonance RLink}
+@* Link: @url{http://www.raisonance.com/products/RLink.php}
+@item @b{STM32 Primer}
+@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
+@item @b{STM32 Primer2}
+@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
+@end itemize
+
 @section USB Other
 @itemize @bullet
 @item @b{USBprog}
@@ -544,7 +610,7 @@ Some key things you should look at and understand are:
 
 @enumerate
 @item The RESET configuration of your debug environment as a hole
-@item Is there a ``work area'' that that OpenOCD can use?
+@item Is there a ``work area'' that OpenOCD can use?
 @* For ARM - work areas mean up to 10x faster downloads.
 @item For MMU/MPU based ARM chips (ie: ARM9 and later) will that work area still be available?
 @item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
@@ -920,7 +986,7 @@ can type a Tcl for() loop, set variables, etc.
 
 @node Daemon Configuration
 @chapter Daemon Configuration
-The commands here are commonly found inthe openocd.cfg file and are
+The commands here are commonly found in the openocd.cfg file and are
 used to specify what TCP/IP ports are used, and how GDB should be
 supported.
 @section init
@@ -1017,6 +1083,11 @@ ft2232_vid_pid 0x0403 0xbdc8
 # jlink interface
 interface jlink
 @end verbatim
+@b{A Raisonance RLink}
+@verbatim
+# rlink interface
+interface rlink
+@end verbatim
 @b{Parallel Port}
 @verbatim
 interface parport
@@ -1066,6 +1137,9 @@ libusb.
 
 @item @b{jlink}
 @* Segger jlink usb adapter
+
+@item @b{rlink}
+@* Raisonance RLink usb adapter
 @comment - End parameters
 @end itemize
 @comment - End Interface
@@ -1247,6 +1321,7 @@ pre_reset and post_reset events.
 @item ft2232: 6MHz / (@var{number}+1)
 @item amt jtagaccel: 8 / 2**@var{number}
 @item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
 @comment end speed list.
 @end itemize
 
@@ -1492,9 +1567,9 @@ have the taps created in the proper order.
 by the ``jtag newtap'' command. The documentation remains here so that
 one can easily convert the old syntax to the new syntax. About the old
 syntax: The old syntax is positional, ie: The 4th parameter is the
-``irmask'' The new syntax requires named prefixes, and supports
-additional options, for example ``-irmask 4'' Please refer to the
-@b{jtag newtap} command for deails.
+``irmask''. The new syntax requires named prefixes, and supports
+additional options, for example ``-irmask 4''. Please refer to the
+@b{jtag newtap} command for details.
 @example
 OLD: jtag_device 8 0x01 0x0e3 0xfe
 NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0xe3 -irmask 0xfe
@@ -1543,7 +1618,7 @@ The IEEE JTAG definition has no concept of a ``disabled'' tap.
 
 @b{jtag tapisenabled DOTTED.NAME}
 
-This command return 1 if the named tap is currently enabled, 0 if not.
+This command returns 1 if the named tap is currently enabled, 0 if not.
 This command exists so that scripts that manipulate a JRC (like the
 Omap3530 has) can determine if OpenOCD thinks a tap is presently
 enabled, or disabled.
@@ -1558,7 +1633,7 @@ creating a ``target'' a JTAG Tap DOTTED.NAME must exist first.
 @section targets [NAME]
 @b{Note:} This command name is PLURAL - not singular.  
 
-With NO parameter, this pural @b{targets} command lists all known
+With NO parameter, this plural @b{targets} command lists all known
 targets in a human friendly form.
 
 With a parameter, this pural @b{targets} command sets the current
@@ -1690,13 +1765,13 @@ with odd reset situations and are not documented here.
 @end itemize
 
 @section Target Events
-At various times, certian things happen, or you want to happen.
+At various times, certain things can happen, or you want them to happen.
 
 Examples:
 @itemize @bullet
 @item What should happen when GDB connects? Should your target reset?
 @item When GDB tries to flash the target, do you need to enable the flash via a special command?
-@item During reset, do you need to write to certian memory locations to reconfigure the SDRAM?
+@item During reset, do you need to write to certain memory location to reconfigure the SDRAM?
 @end itemize
 
 All of the above items are handled by target events.
@@ -1708,7 +1783,7 @@ Syntactially, the option is: ``-event NAME BODY'' where NAME is a
 target event name, and BODY is a tcl procedure or string of commands
 to execute. 
 
-The programers model is the: ``-command'' option used in Tcl/Tk
+The programmers model is the ``-command'' option used in Tcl/Tk
 buttons and events. Below are two identical examples, the first
 creates and invokes small procedure. The second inlines the procedure.
 
@@ -1721,8 +1796,8 @@ creates and invokes small procedure. The second inlines the procedure.
    mychip.cpu configure -event gdb-attach @{ puts "Reset..." ; reset halt @}
 @end example
 
-Current Events
-
+@section Current Events
+The following events are available:
 @itemize @bullet
 @item @b{debug-halted}
 @* The target has halted for debug reasons (ie: breakpoint)
@@ -1786,6 +1861,22 @@ Current Events
 @* Success
 @item @b{resumed}
 @* Target has resumed
+@item @b{tap-enable}
+@* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-enable @{
+  puts "Enabling CPU"
+  ...
+@}
+@end example
+@item @b{tap-disable}
+@*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-disable @{
+  puts "Disabling CPU"
+  ...
+@}
+@end example
 @end itemize
 
 
@@ -1822,13 +1913,13 @@ command.
 @comment end TYPES
 @end itemize
 @item @b{PARAMS}
-@*PARAMs are various target configure parameters, the following are manditory
-at configuration.
-@comment START manditory
+@*PARAMs are various target configure parameters, the following are mandatory
+at configuration:
+@comment START mandatory
 @itemize @bullet
 @item @b{-endian big|little}
 @item @b{-chain-position DOTTED.NAME}
-@comment end MANDITORY
+@comment end MANDATORY
 @end itemize
 @comment END params
 @end itemize
@@ -3269,7 +3360,7 @@ OpenOCD.
 @section TCL Rule #1
 There is a famous joke, it goes like this:
 @enumerate
-@item Rule #1: The wife is aways correct
+@item Rule #1: The wife is always correct
 @item Rule #2: If you think otherwise, See Rule #1
 @end enumerate
 
@@ -3280,7 +3371,7 @@ The TCL equal is this:
 @item Rule #2: If you think otherwise, See Rule #1
 @end enumerate
 
-As in the famous joke, the consiquences of Rule #1 are profound. Once
+As in the famous joke, the consequences of Rule #1 are profound. Once
 you understand Rule #1, you will understand TCL.
 
 @section TCL Rule #1b
@@ -3350,9 +3441,9 @@ nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of
 28/nov/2008, Jim/OpenOCD does not have a date command.
 @end itemize
 
-@section Consiquences of Rule 1/2/3/4
+@section Consequences of Rule 1/2/3/4
 
-The consiquences of Rule 1 is profound.
+The consequences of Rule 1 is profound.
 
 @subsection Tokenizing & Execution.