Uwe Hermann <uwe@hermann-uwe.de>
- Explicitly mention autoconf >= 2.59 as requirement (as per configure.in). Also automake >= 1.9 (though I'm not sure which if that's really the minimum requirement). - Document various missing configure options. - Fix various typos and inconsistencies. git-svn-id: svn://svn.berlios.de/openocd/trunk@1426 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
oharboe
parent
2b8aa1d058
commit
0cfcd0bc9b
134
doc/openocd.texi
134
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} - Parallel Port [see below]
|
||||
@option{--enable-parport_ppdev} - Enable use of ppdev (/dev/parportN) for parport.
|
||||
@item
|
||||
@option{--enable-parport_giveio} - Parallel Port [see below]
|
||||
@option{--enable-parport_giveio} - Enable use of giveio for parport instead of ioperm.
|
||||
@item
|
||||
@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
|
||||
@option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver.
|
||||
@item
|
||||
@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
|
||||
@option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger.
|
||||
@item
|
||||
@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
|
||||
@option{--enable-ioutil} - Enable ioutil functions - useful for standalone OpenOCD implementations.
|
||||
@item
|
||||
@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
|
||||
|
||||
Linux FTDICHIP solution
|
||||
Cygwin FTDICHIP solution:
|
||||
./configure --prefix=/home/duane/mytools \
|
||||
--enable-ft2232_ftd2xx \
|
||||
--with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
|
||||
--enable-ft2232_ftd2xx \
|
||||
--with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
|
||||
|
||||
Cygwin/Linux LIBFTDI solution
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue