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

diff --git a/doc/openocd.texi b/doc/openocd.texi
index fb459ddee82708fba48e6ca3c3f25d00e1365dcc..d3e119cf38187ac1d9bd01b965932c7c302f73bf 100644 (file)
--- 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