diff options
| -rw-r--r-- | README | 389 | ||||
| -rw-r--r-- | doc/openocd.texi | 292 |
2 files changed, 407 insertions, 274 deletions
@@ -1,3 +1,390 @@ -openocd.texi is the authoritative source of OpenOCD documentation +Welcome to OpenOCD! +=================== + +OpenOCD provides on-chip programming and debugging support with a +layered architecture of JTAG interface and TAP support, debug target +support (e.g. ARM, MIPS), and flash chip drivers (e.g. CFI, NAND, etc.). +Several network interfaces are available for interactiving with OpenOCD: +HTTP, telnet, TCL, and GDB. The GDB server enables OpenOCD to function +as a "remote target" for source-level debugging of embedded systems +using the GNU GDB program. + +This README file contains an overview of the following topics: +- how to find and build more OpenOCD documentation, +- the build process +- packaging tips. +- configuration options + +===================== +OpenOCD Documentation +===================== + +In addition to in-tree documentation, the latest documentation may be +viewed on-line at the following URLs: + + OpenOCD User's Guide: + http://openocd.berlios.de/doc/html/index.html + + OpenOCD Developer's Manual: + http://openocd.berlios.de/doc/doxygen/index.html + +These reflect the latest development versions, so the following section +introduces how to build the complete documentation from the package. + + +For more information, refer to these documents or contact the developers +by subscribing to the OpenOCD developer mailing list: + + openocd-development@lists.berlios.de + +Building the OpenOCD Documentation +---------------------------------- + +The OpenOCD User's Guide can be produced in two different format: + + # If PDFVIEWER is set, this creates and views the PDF User Guide. + make pdf && ${PDFVIEWER} doc/openocd.pdf + + # If HTMLVIEWER is set, this creates and views the HTML User Guide. + make html && ${HTMLVIEWER} doc/openocd.html/index.html + +The OpenOCD Developer Manual contains information about the internal +architecture and other details about the code: + + make doxygen + + # If HTMLVIEWER is set, this views the HTML Doxygen output. + ${HTMLVIEWER} doxyegen/index.html + +The remaining sections describe how to configure the system such that +you can build the in-tree documentation. + +================== +Installing OpenOCD +================== + +A Note to OpenOCD Users +----------------------- + +If you would rather be working "with" OpenOCD rather than "on" it, your +operating system or interface supplier may provide binaries for you in a +convenient package. + +Such packages should be more stable than SVN trunk, where bleeding-edge +development takes place. These "Packagers" produce binary releases of +OpenOCD after the developers produces new "stable" versions of the +source code. Previous versions of OpenOCD cannot be used to diagnosed +problems with the current release, so users are encouraged to keep in +contact with their distribution package maintainers or interface vendors +to ensure suitable upgrades appear regularly. + +Users of these binary versions of OpenOCD must contact their Packager to +ask for support or newer versions of the binaries; the OpenOCD +developers do not support packages directly. + +A Note to OpenOCD Packagers +--------------------------- + +You are a PACKAGER of OpenOCD if you: + +- Sell dongles: and include pre-built binaries +- Supply tools: A complete development solution +- Supply IDEs: like Eclipse, or RHIDE, etc. +- Build packages: RPM files, or DEB files for a Linux Distro + +As a PACKAGER, you will experience first reports of most issues. +When you fix those problems for your users, your solution may help +prevent hundreds (if not thousands) of other questions from other users. + +If something does not work for you, please work to inform the OpenOCD +developers know how to improve the system or documentation to avoid +future problems, and follow-up to help us ensure the issue will be fully +resolved in our future releases. + +That said, the OpenOCD developers would also like you to follow a few +suggestions: + +- Send patches, including config files, upstream. +- Always build with printer ports enabled. +- Use libftdi + libusb for FT2232 support. + +Remember, the FTD2XX library cannot be used in binary distributions, due +to restrictions of the GPL v2. + +================ +Building OpenOCD +================ + +The INSTALL file contains generic instructions for running 'configure' +and compiling the OpenOCD source code. That file is provided by default +for all GNU automake packages, and + +if you are not familiar with the GNU autotools, then you should read +those instructions first. +Still, the +remainder of this document tries to provide complete instructions for +those looking for a quick-install + +OpenOCD Dependencies +-------------------- + +You will need to install the appropriate driver files, if you want to +build support for a USB or FTDI-based interface: + +- ft2232, jlink, rlink, vsllink, usbprog, arm-jtag-ew: + - libusb: required for portable communication with USB dongles +- ft2232 also requires: + - libftdi: http://www.intra2net.com/opensource/ftdi/ *OR* + - ftd2xx: http://www.ftdichip.com/Drivers/D2XX.htm, + or the Amontec version (from @uref{http://www.amontec.com}), for + easier support of JTAGkey's vendor and product IDs. + +Compiling OpenOCD +----------------- + +To build OpenOCD (on both Linux and Cygwin), use the following sequence +of commands: + + ./configure [with some options listed in the next section] + make + make install + +The 'configure' step generates the Makefiles required to build OpenOCD, +usually with one or more options provided to it. The first 'make' step +will build OpenOCD and place the final executable in ./src/. The +final (optional) step, ``make install'', places all of the files in the +required location. + +Configuration Options +--------------------- + +The configure script takes numerous options, specifying which JTAG +interfaces should be included (among other things). The following list +of options was extracted from the output of './configure --help'. Other +options may be available there: + + --enable-maintainer-mode enable make rules and dependencies not useful + (and sometimes confusing) to the casual installer + NOTE: This option is *required* for SVN builds! + It should *not* be used to build a release. + + --enable-dummy Enable building the dummy JTAG port driver + + --enable-ft2232_libftdi Enable building support for FT2232 based devices + using the libftdi driver, opensource alternate of + FTD2XX + --enable-ft2232_ftd2xx Enable building support for FT2232 based devices + using the FTD2XX driver from ftdichip.com + --enable-ftd2xx-highspeed + Enable building support for FT2232H and + FT4232H-based devices (requires >=libftd2xx-0.4.16) + + --enable-gw16012 Enable building support for the Gateworks GW16012 + JTAG Programmer + + --enable-parport Enable building the pc parallel port driver + --disable-parport-ppdev Disable use of ppdev (/dev/parportN) for parport + (for x86 only) + --enable-parport-giveio Enable use of giveio for parport (for CygWin only) + + --enable-presto_libftdi Enable building support for ASIX Presto Programmer + using the libftdi driver + --enable-presto_ftd2xx Enable building support for ASIX Presto Programmer + using the FTD2XX driver + + --enable-amtjtagaccel Enable building the Amontec JTAG-Accelerator driver + --enable-arm-jtag-ew Enable building support for the Olimex ARM-JTAG-EW + Programmer + --enable-jlink Enable building support for the Segger J-Link JTAG + Programmer + --enable-rlink Enable building support for the Raisonance RLink + JTAG Programmer + --enable-usbprog Enable building support for the usbprog JTAG + Programmer + --enable-vsllink Enable building support for the Versaloon-Link JTAG + Programmer + + --enable-oocd_trace Enable building support for the OpenOCD+trace ETM + capture device + + --enable-ep93xx Enable building support for EP93xx based SBCs + --enable-at91rm9200 Enable building support for AT91RM9200 based SBCs + + --enable-ecosboard Enable building support for eCos based JTAG debugger + --enable-zy1000 Enable ZY1000 interface + + --enable-minidriver-dummy + Enable the dummy minidriver. + + --enable-ioutil Enable ioutil functions - useful for standalone + OpenOCD implementations + --enable-httpd Enable builtin httpd server - useful for standalone + OpenOCD implementations + +Miscellaneous Configure Options +------------------------------- + +The following additional options may also be useful: + + --disable-assert turn off assertions + + --enable-verbose Enable verbose JTAG I/O messages (for debugging). + --enable-verbose-jtag-io + Enable verbose JTAG I/O messages (for debugging). + --enable-verbose-usb-io Enable verbose USB I/O messages (for debugging) + --enable-verbose-usb-comms + Enable verbose USB communication messages (for + debugging) + --enable-malloc-logging Include free space in logging messages (requires + malloc.h). + + --disable-gccwarnings Disable extra gcc warnings during build. + --disable-wextra Disable extra compiler warnings + --disable-werror Do not treat warnings as errors + + --enable-release Enable building of an OpenOCD release. This + option is intended for project maintainers. + It simply omits the svn version string when + the openocd -v is executed (to KISS). + + --disable-option-checking + Ignore unrecognized --enable and --with options. + --disable-dependency-tracking speeds up one-time build + --enable-shared[=PKGS] build shared libraries [default=no] + --enable-static[=PKGS] build static libraries [default=yes] + +Parallel Port Dongles +--------------------- + +If you want to access the parallel port using the PPDEV interface you +have to specify both --enable-parport AND --enable-parport-ppdev, since the +the later option is an option to the parport driver (see +http://forum.sparkfun.com/viewtopic.php?t=3795 for more info). + +The same is true for the --enable-parport-giveio option, you +have to use both the --enable-parport AND the --enable-parport-giveio +option if you want to use giveio instead of ioperm parallel port access +method. + +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. + +Using LIBFTDI +------------- + +For both Linux and Windows, both libusb and libftdi must be built and +installed. To use the newer FT2232H chips, supporting RTCK and USB high +speed (480 Mbps), you need libftdi version 0.16 or newer. Many Linux +distributions provide suitable packages for these libraries. + +For Windows, libftdi is supported with versions 0.14 and later. + +With these prerequisites met, configure the libftdi solution like this: + + ./configure --prefix=/path/for/your/install --enable-ft2232_libftdi + +Then type ``make'', and perhaps ``make install''. + +Using FTDI's FTD2XX +------------------- + +Some claim the (closed) FTDICHIP.COM solution is faster, which +is the motivation for supporting it even though its licensing restricts +it to non-redistributable OpenOCD binaries, and it is not available for +all operating systems used with OpenOCD. You may, however, build such +copies for personal use. + +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 FTDICHIP does not supply means to install these files "in an +appropriate place." + +If your distribution does not package these, there are several +'./configure' options to solve this problem: + + --with-ftd2xx-win32-zipdir + Where (CYGWIN/MINGW) the zip file from ftdichip.com + was unpacked <default=search> + --with-ftd2xx-linux-tardir + Where (Linux/Unix) the tar file from ftdichip.com + was unpacked <default=search> + --with-ftd2xx-lib Use static or shared ftd2xx libs on default static + +If you are using the FTDICHIP.COM driver, download and unpack the +Windows or Linux FTD2xx drivers from the following location: + + http://www.ftdichip.com/Drivers/D2XX.htm + +Remember, this library is binary-only, while OpenOCD is licenced +according to GNU GPLv2 without any exceptions. That means that +_distributing_ copies of OpenOCD built with the FTDI code would violate +the OpenOCD licensing terms. + + +Cygwin/Win32 Notes +****************** + +The Cygwin/Win32 ZIP file contains a directory named ftd2xx.win32. +Assuming that you have extracted this archive in the same directory as +the OpenOCD package, you could configure with options like the following: + + ./configure \ + --enable-ft2232_ftd2xx \ + --with-ftd2xx-win32-zipdir=../ftd2xx.win32 \ + ... other options ... + +Linux Notes +*********** + +The Linux tar.gz archive contains a directory named libftd2xx0.4.16 +(or similar). Assuming that you have extracted this archive in the same +directory as the OpenOCD package, you could configure with options like +the following: + + ./configure \ + --enable-ft2232_ftd2xx \ + --with-ft2xx-linux-tardir=../libftd2xx0.4.16 \ + ... other options ... + +================================= +Obtaining OpenOCD From Subversion +--------------------------------- + +You can download the current SVN version with an SVN client of your +choice from the following repositories: + + svn://svn.berlios.de/openocd/trunk +or + http://svn.berlios.de/svnroot/repos/openocd/trunk + +Using the SVN command line client, you can use the following command to +fetch the latest version (make sure there is no (non-svn) directory +called "openocd" in the current directory): + + svn checkout svn://svn.berlios.de/openocd/trunk openocd + +If you prefer GIT based tools, the @command{git-svn} package works too: + + git svn clone -s svn://svn.berlios.de/openocd + +Tips For Building From The Subversion Repository +************************************************ + +Building OpenOCD from a repository 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 was an observation gathered from the logs of +one user; please correct us if this is wrong. + +1) Run './bootstrap' to create the 'configure' script and prepare + the build process for your host system. + +2) Run './configure --enable-maintainer-mode' with other options. diff --git a/doc/openocd.texi b/doc/openocd.texi index b1aae199..363165be 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -61,7 +61,6 @@ Free Documentation License''. @menu * About:: About OpenOCD * Developers:: OpenOCD Developers -* Building OpenOCD:: Building OpenOCD From SVN * JTAG Hardware Dongles:: JTAG Hardware Dongles * About JIM-Tcl:: About JIM-Tcl * Running:: Running OpenOCD @@ -174,9 +173,25 @@ or expand the OpenOCD source code. @section OpenOCD Subversion Repository -The ``Building From Source'' section provides instructions to retrieve -and and build the latest version of the OpenOCD source code. -@xref{Building OpenOCD}. +You can download the current SVN version with an SVN client of your +choice from the following repositories: + + svn://svn.berlios.de/openocd/trunk +or + http://svn.berlios.de/svnroot/repos/openocd/trunk + +Using the SVN command line client, you can use the following command to +fetch the latest version (make sure there is no (non-svn) directory +called "openocd" in the current directory): + + svn checkout svn://svn.berlios.de/openocd/trunk openocd + +If you prefer GIT based tools, the @command{git-svn} package works too: + + git svn clone -s svn://svn.berlios.de/openocd + +The ``README'' file contains the instructions for building the project +from the repository. Developers that want to contribute patches to the OpenOCD system are @b{strongly} encouraged to base their work off of the most recent trunk @@ -209,275 +224,6 @@ SVN commits to keep pace with the ongoing changes: @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn} -@node Building OpenOCD -@chapter Building OpenOCD -@cindex building - -@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 Packagers Please Read! - -You are a @b{PACKAGER} of OpenOCD if you - -@enumerate -@item @b{Sell dongles} and include pre-built binaries -@item @b{Supply tools} i.e.: A complete development solution -@item @b{Supply IDEs} like Eclipse, or RHIDE, etc. -@item @b{Build packages} i.e.: RPM files, or DEB files for a Linux Distro -@end enumerate - -As a @b{PACKAGER}, you will experience first reports of most issues. -When you fix those problems for your users, your solution may help -prevent hundreds (if not thousands) of other questions from other users. - -If something does not work for you, please work to inform the OpenOCD -developers know how to improve the system or documentation to avoid -future problems, and follow-up to help us ensure the issue will be fully -resolved in our future releases. - -That said, the OpenOCD developers would also like you to follow a few -suggestions: - -@enumerate -@item Send patches, including config files, upstream. -@item Always build with printer ports enabled. -@item Use libftdi + libusb for FT2232 support. -@end enumerate - -@section Building From Source - -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} - -or - - @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk} - -Using the SVN command line client, you can use the following command to fetch the -latest version (make sure there is no (non-svn) directory called "openocd" in the -current directory): - -@example - svn checkout svn://svn.berlios.de/openocd/trunk openocd -@end example - -If you prefer GIT based tools, the @command{git-svn} package works too: - -@example - git svn clone -s svn://svn.berlios.de/openocd -@end example - -Building OpenOCD from a repository 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 -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}), -or the Amontec version (from @uref{http://www.amontec.com}), -for easier support of JTAGkey's vendor and product IDs. -@end itemize - -libftdi is supported under Windows. Do not use versions earlier than 0.14. -To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps), -you need libftdi version 0.16 or newer. - -Some people say that FTDI's libftd2xx code provides better performance. -However, it is binary-only, while OpenOCD is licenced according -to GNU GPLv2 without any exceptions. -That means that @emph{distributing} copies of OpenOCD built with -the FTDI code would violate the OpenOCD licensing terms. -You may, however, build such copies for personal use. - -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 (among other things): - -@itemize @bullet -@item -@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_giveio} - Enable use of giveio for parport instead of ioperm. -@item -@option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver. -@item -@option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger. -@item -@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} - Support FT2232-family chips using -the closed-source library from FTDICHIP.COM -(result not for re-distribution). -@item -@option{--enable-ft2232_libftdi} - Support FT2232-family chips using -a GPL'd ft2232 support library (result OK for re-distribution). -@item -@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver, -give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked. -@item -@option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver -on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked. -@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}. -The 'shared' value is supported, however you must manually install the required -header files and shared libraries in an appropriate place. -@item -@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver. -@item -@option{--enable-presto_ftd2xx} - Enable building support for ASIX Presto programmer using the FTD2XX driver. -@item -@option{--enable-usbprog} - Enable building support for the USBprog JTAG programmer. -@item -@option{--enable-oocd_trace} - Enable building support for the OpenOCD+trace ETM capture device. -@item -@option{--enable-jlink} - Enable building support for the Segger J-Link JTAG programmer. -@item -@option{--enable-vsllink} - Enable building support for the Versaloon-Link JTAG programmer. -@item -@option{--enable-rlink} - Enable building support for the Raisonance RLink JTAG programmer. -@item -@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 - -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). - -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 -FTDICHIP.COM closed source driver, or (2) the open (and free) driver -libftdi. Some claim the (closed) FTDICHIP.COM solution is faster, -which is the motivation for supporting it even though its licensing -restricts it to non-redistributable OpenOCD binaries, and it is -not available for all operating systems used with OpenOCD. - -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 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: - -@enumerate -@item Check out the latest version of ``openocd'' from SVN. - -@item If you are using the FTDICHIP.COM driver, download -and unpack the Windows or Linux FTD2xx drivers -(@uref{http://www.ftdichip.com/Drivers/D2XX.htm}). -If you are using the libftdi driver, install that package -(e.g. @command{apt-get install libftdi} on systems with APT). - -@example -/home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents -/home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents -@end example - -@item Configure with options resembling the following. - -@enumerate a -@item Cygwin FTDICHIP solution: -@example -./configure --prefix=/home/duane/mytools \ - --enable-ft2232_ftd2xx \ - --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32 -@end example - -@item Linux FTDICHIP solution: -@example -./configure --prefix=/home/duane/mytools \ - --enable-ft2232_ftd2xx \ - --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16 -@end example - -@item Cygwin/Linux LIBFTDI solution ... assuming that -@itemize -@item For Windows -- that the Windows port of LIBUSB is in place. -@item For Linux -- that libusb has been built/installed and is in place. -@item That libftdi has been built and installed (relies on libusb). -@end itemize - -Then configure the libftdi solution like this: - -@example -./configure --prefix=/home/duane/mytools \ - --enable-ft2232_libftdi -@end example -@end enumerate - -@item Then just type ``make'', and perhaps ``make install''. -@end enumerate - - -@section Miscellaneous Configure Options - -@itemize @bullet -@item -@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 an OpenOCD release, generally -this is for developers. It simply omits the svn version string when the -openocd @option{-v} is executed. -@end itemize - @node JTAG Hardware Dongles @chapter JTAG Hardware Dongles @cindex dongles |