diff options
| -rw-r--r-- | doc/openocd.texi | 132 |
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 |