summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/openocd.texi132
1 files changed, 78 insertions, 54 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi
index fb459dde..d3e119cf 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -51,7 +51,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
@insertcopying
@menu
-* About:: About OpenOCD.
+* About:: About OpenOCD
* Developers:: OpenOCD Developers
* Building:: Building OpenOCD
* JTAG Hardware Dongles:: JTAG Hardware Dongles
@@ -71,7 +71,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
-* Upgrading:: Deprecated/Removed commands
+* Upgrading:: Deprecated/Removed Commands
* Target Library:: Target Library
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
@@ -80,7 +80,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
-* OpenOCD Index:: Main index.
+* OpenOCD Index:: Main Index
@end menu
@node About
@@ -95,17 +95,17 @@ devices.
with the JTAG (IEEE 1149.1) compliant taps on your target board.
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
-Based, Parallel Port Based, and other standalone boxes that run
+based, parallel port based, and other standalone boxes that run
OpenOCD internally. See the section titled: @xref{JTAG Hardware Dongles}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be
-debugged via the GDB Protocol.
+debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
compatible flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3 and
+internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
STM32x). Preliminary support for using the LPC3180's NAND flash
controller is included.
@@ -121,7 +121,7 @@ are welcome to participate.
Other developers have contributed support for additional targets and flashes as well
as numerous bugfixes and enhancements. See the AUTHORS file for regular contributors.
-The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}
+The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}.
@node Building
@chapter Building
@@ -135,7 +135,7 @@ stable than SVN trunk where bleeding edge development takes place.
@section Packagers Please Read!
-If you are a @b{PACKAGER} of OpenOCD if you
+You are a @b{PACKAGER} of OpenOCD if you
@enumerate
@item @b{Sell dongles} and include pre-built binaries
@@ -151,31 +151,29 @@ please let us know. That said, would also like you to follow a few
suggestions:
@enumerate
-@item @b{Always build with printer ports enabled}
-@item @b{Try to use LIBFTDI + LIBUSB where possible}. You cover more bases
+@item @b{Always build with printer ports enabled.}
+@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
@end enumerate
-It is your decision..
-
@itemize @bullet
-@item @b{Why YES to LIBFTDI + LIBUSB}
+@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{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)
+@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
@itemize @bullet
-@item @b{LESS} Some say it is slower.
+@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 SVN client of your choice from the
+You can download the current SVN version with an SVN client of your choice from the
following repositories:
@uref{svn://svn.berlios.de/openocd/trunk}
@@ -192,8 +190,8 @@ current directory):
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
-Building OpenOCD requires a recent version of the GNU autotools.
-On my build system, I'm using autoconf 2.13 and automake 1.9. For building on Windows,
+Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
+For building on Windows,
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
paths, resulting in obscure dependency errors (This is an observation I've gathered
@@ -201,72 +199,93 @@ from the logs of one user - correct me if I'm wrong).
You further need the appropriate driver files, if you want to build support for
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{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
+homepage (@uref{http://www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
@end itemize
-libftdi is supported under Windows. Do not use versions earlier then 0.14.
+libftdi is supported under Windows. Do not use versions earlier than 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
a kernel module, only a user space library.
To build OpenOCD (on both Linux and Cygwin), use the following commands:
+
@example
./bootstrap
@end example
+
Bootstrap generates the configure script, and prepares building on your system.
+
@example
./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/, the last step, ``make install'' is optional.
The configure script takes several options, specifying which JTAG interfaces
-should be included:
+should be included (among other things):
@itemize @bullet
@item
-@option{--enable-parport} - Bit bang pc printer ports.
+@option{--enable-parport} - Enable building the PC parallel port driver.
+@item
+@option{--enable-parport_ppdev} - Enable use of ppdev (/dev/parportN) for parport.
@item
-@option{--enable-parport_ppdev} - Parallel Port [see below]
+@option{--enable-parport_giveio} - Enable use of giveio for parport instead of ioperm.
@item
-@option{--enable-parport_giveio} - Parallel Port [see below]
+@option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver.
@item
-@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
+@option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger.
@item
-@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
+@option{--enable-ioutil} - Enable ioutil functions - useful for standalone OpenOCD implementations.
@item
-@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
+@option{--enable-httpd} - Enable builtin httpd server - useful for standalone OpenOCD implementations.
+@item
+@option{--enable-ep93xx} - Enable building support for EP93xx based SBCs.
+@item
+@option{--enable-at91rm9200} - Enable building support for AT91RM9200 based SBCs.
+@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).
+@item
+@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
@item
@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.
+@option{--with-ftd2xx-linux-tardir=PATH} - Linux only. Equivalent 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.
+@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}. The 'shared' value 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}
+@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
@item
-@option{--enable-usbprog}
+@option{--enable-presto_ftd2xx} - Enable building support for ASIX Presto programmer using the FTD2XX driver.
@item
-@option{--enable-presto_libftdi}
+@option{--enable-usbprog} - Enable building support for the USBprog JTAG programmer.
@item
-@option{--enable-presto_ftd2xx}
+@option{--enable-oocd_trace} - Enable building support for the OpenOCD+trace ETM capture device.
@item
-@option{--enable-jlink} - From SEGGER
+@option{--enable-jlink} - Enable building support for the Segger J-Link JTAG programmer.
@item
-@option{--enable-vsllink}
+@option{--enable-vsllink} - Enable building support for the Versaloon-Link JTAG programmer.
@item
-@option{--enable-rlink} - Raisonance.com dongle.
+@option{--enable-rlink} - Enable building support for the Raisonance RLink JTAG programmer.
@item
-@option{--enable-arm-jtag-ew} - Olimex ARM-JTAG-EW dongle.
+@option{--enable-arm-jtag-ew} - Enable building support for the Olimex ARM-JTAG-EW programmer.
+@item
+@option{--enable-dummy} - Enable building the dummy port driver.
@end itemize
@section Parallel Port Dongles
@@ -276,6 +295,9 @@ both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} optio
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).
+The same is true for the @option{--enable-parport_giveio} option, you have to
+use both the @option{--enable-parport} AND the @option{--enable-parport_giveio} option if you want to use giveio instead of ioperm parallel port access method.
+
@section FT2232C Based USB Dongles
There are 2 methods of using the FTD2232, either (1) using the
@@ -292,51 +314,53 @@ 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})
+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.
+ /home/duane/libftd2xx0.4.16 => the Linux TAR.GZ 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
+Cygwin FTDICHIP solution:
+ ./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
-Linux FTDICHIP solution
+Linux FTDICHIP solution:
./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
+ --enable-ft2232_ftd2xx \
+ --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
-Cygwin/Linux LIBFTDI solution
+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.
+ 1b) For Linux: libusb has been built/installed and is in place.
2) And libftdi has been built and installed
Note: libftdi - relies upon libusb.
./configure --prefix=/home/duane/mytools \
- --enable-ft2232_libftdi
+ --enable-ft2232_libftdi
@end example
4) Then just type ``make'', and perhaps ``make install''.
-@section Miscellaneous configure options
+@section Miscellaneous Configure Options
@itemize @bullet
@item
-@option{--enable-gccwarnings} - enable extra gcc warnings during build.
+@option{--disable-option-checking} - Ignore unrecognized @option{--enable} and @option{--with} options.
+@item
+@option{--enable-gccwarnings} - Enable extra gcc warnings during build.
Default is enabled.
@item
-@option{--enable-release} - enable building of a openocd release, generally
+@option{--enable-release} - Enable building of an OpenOCD release, generally
this is for developers. It simply omits the svn version string when the
openocd @option{-v} is executed.
@end itemize