X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=README;h=dffa4886291087b0346fbb19aa0ee8b997998c37;hp=f60b67bf0a9699180b478ce7e606b67f73eb0074;hb=e61638b7320ea32806df3b01d9c20707dfbe9553;hpb=ef30f22fd3355f668b23905f50bab4671f803ab1 diff --git a/README b/README index f60b67bf0a..dffa488629 100644 --- a/README +++ b/README @@ -2,45 +2,83 @@ 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. +layered architecture of JTAG interface and TAP support including: + +- (X)SVF playback to faciliate automated boundary scan and FPGA/CPLD + programming; +- debug target support (e.g. ARM, MIPS): single-stepping, + breakpoints/watchpoints, gprof profiling, etc; +- flash chip drivers (e.g. CFI, NAND, internal flash); +- embedded TCL interpreter for easy scripting. + +Several network interfaces are available for interacting with OpenOCD: +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 (and the others who talk GDB protocol, e.g. IDA +Pro). This README file contains an overview of the following topics: + +- quickstart instructions, - how to find and build more OpenOCD documentation, -- the build process +- list of the supported hardware, +- the installation and build process, - packaging tips. -- configuration options + + +============================ +Quickstart for the impatient +============================ + +If you have a popular board then just start OpenOCD with its config, +e.g.: + + openocd -f board/stm32f4discovery.cfg + +If you are connecting a particular adapter with some specific target, +you need to source both the jtag interface and the target configs, +e.g.: + + openocd -f interface/ftdi/jtagkey2.cfg -f target/ti_calypso.cfg + +NB: when using an FTDI-based adapter you should prefer configs in the +ftdi directory; the old configs for the ft2232 are deprecated. + +After OpenOCD startup, connect GDB with + + (gdb) target extended-remote localhost:3333 + ===================== OpenOCD Documentation ===================== -In addition to in-tree documentation, the latest documentation may be -viewed on-line at the following URLs: +In addition to the in-tree documentation, the latest manuals may be +viewed online at the following URLs: - OpenOCD User's Guide: - http://openocd.berlios.de/doc/html/index.html + OpenOCD User's Guide: + http://openocd.sourceforge.net/doc/html/index.html - OpenOCD Developer's Manual: - http://openocd.berlios.de/doc/doxygen/index.html + OpenOCD Developer's Manual: + http://openocd.sourceforge.net/doc/doxygen/html/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 + openocd-devel@lists.sourceforge.net Building the OpenOCD Documentation ---------------------------------- -The OpenOCD User's Guide can be produced in two different format: +By default the OpenOCD build process prepares documentation in the +"Info format" and installs it the standard way, so that "info openocd" +can access it. + +Additionally, the OpenOCD User's Guide can be produced in the +following different formats: # If PDFVIEWER is set, this creates and views the PDF User Guide. make pdf && ${PDFVIEWER} doc/openocd.pdf @@ -52,38 +90,63 @@ The OpenOCD Developer Manual contains information about the internal architecture and other details about the code: # NB! make sure doxygen is installed, type doxygen --version - make doxygen + make doxygen && ${HTMLVIEWER} doxygen/index.html + + +================== +Supported hardware +================== + +JTAG adapters +------------- - # If HTMLVIEWER is set, this views the HTML Doxygen output. - ${HTMLVIEWER} doxygen/index.html +AICE, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, +BCM2835, Bus Blaster, Buspirate, Chameleon, Cortino, DENX, DLC 5, +DLP-USB1232H, embedded projects, eStick, FlashLINK, FlossJTAG, +Flyswatter, Flyswatter2, Gateworks, Hoegl, ICDI, ICEBear, J-Link, +JTAG VPI, JTAGkey, JTAGkey2, JTAG-lock-pick, KT-Link, Lisa/L, +LPC1768-Stick, MiniModule, NGX, NXHX, OOCDLink, Opendous, OpenJTAG, +Openmoko, OpenRD, OSBDM, Presto, Redbee, RLink, SheevaPlug devkit, +Stellaris evkits, ST-LINK (SWO tracing supported), +STM32-PerformanceStick, STR9-comStick, sysfsgpio, TUMPA, Turtelizer, +ULINK, USB-A9260, USB-Blaster, USB-JTAG, USBprog, VPACLink, VSLLink, +Wiggler, XDS100v2, Xverve. + +Debug targets +------------- + +ARM11, ARM7, ARM9, AVR32, Cortex-A, Cortex-R, Cortex-M, +Feroceon/Dragonite, DSP563xx, DSP5680xx, FA526, MIPS EJTAG, NDS32, +XScale. + +Flash drivers +------------- + +ADUC702x, AT91SAM, AVR, CFI, DSP5680xx, EFM32, EM357, FM3, Kinetis, +LPC2000, LPC2900, LPCSPIFI, Milandr, NuMicro, PIC32mx, Stellaris, +STM32, STMSMI, STR7x, STR9x; NAND controllers of AT91SAM9, LPC3180, +LPC32xx, i.MX31, MXC, NUC910, Orion/Kirkwood, S3C24xx, S3C6400. -The remaining sections describe how to configure the system such that -you can build the in-tree documentation. ================== Installing OpenOCD ================== -On Linux, you may have permissions problems to address. The best -way to do this is to use the contrib/udev.rules file. It probably -belongs somewhere in /etc/udev/rules.d, but consult your operating -system documentation to be sure. In particular, make sure that it -matches the syntax used by your operating system's version of udev. - 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. +operating system or JTAG interface supplier may provide binaries for +you in a convenient-enough package. + +Such packages may be more stable than git mainline, where +bleeding-edge development takes place. These "Packagers" produce +binary releases of OpenOCD after the developers produces new "release" +versions of the source code. Previous versions of OpenOCD cannot be +used to diagnose 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 @@ -94,10 +157,9 @@ 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 +- Sell dongles and include pre-built binaries; +- Supply tools or IDEs (a development solution integrating OpenOCD); +- Build packages (e.g. RPM or DEB files for a GNU/Linux distribution). As a PACKAGER, you will experience first reports of most issues. When you fix those problems for your users, your solution may help @@ -111,21 +173,25 @@ 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. +- Send patches, including config files, upstream, participate in the + discussions; +- Enable all the options OpenOCD supports, even those unrelated to your + particular hardware; +- Use "ftdi" interface adapter driver for the FTDI-based devices. + +As a PACKAGER, never link against the FTD2XX library, as the resulting +binaries can't be legally distributed, due to the restrictions of the +GPL. -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. If you are not familiar with the GNU -autotools, then you should read those instructions first. +and compiling the OpenOCD source code. That file is provided by +default for all GNU autotools packages. If you are not familiar with +the GNU autotools, then you should read those instructions first. The remainder of this document tries to provide some instructions for those looking for a quick-install. @@ -133,214 +199,120 @@ those looking for a quick-install. OpenOCD Dependencies -------------------- -Presently, GCC is required to build OpenOCD. The developers have begun -to enforce strict code warnings (-Wall, -Werror, -Wextra, and more) and -use C99-specific features: inline functions, named initializers, mixing -declarations with code, and other tricks. While it may be possible to -use other compilers, they must be somewhat modern and could require -extending support to conditionally remove GCC-specific extensions. - -Also, you 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 http://www.amontec.com), for - easier support of JTAGkey's vendor and product IDs. - -Many Linux distributions provide these packages through their automated -installation and update mechanisms; however, some Linux versions include -older versions of libftdi. In particular, using Ubuntu 8.04 has been -problematic, but newer versions of Ubuntu do not have this problem. +GCC or Clang is currently required to build OpenOCD. The developers +have begun to enforce strict code warnings (-Wall, -Werror, -Wextra, +and more) and use C99-specific features: inline functions, named +initializers, mixing declarations with code, and other tricks. While +it may be possible to use other compilers, they must be somewhat +modern and could require extending support to conditionally remove +GCC-specific extensions. -Compiling OpenOCD ------------------ +You'll also need: -To build OpenOCD (on both Linux and Cygwin), use the following sequence -of commands: +- make +- libtool +- pkg-config >= 0.23 (or compatible) - ./configure [with some options listed in the next section] - make - make install +Additionally, for building from git: -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. +- autoconf >= 2.59 +- automake >= 1.9 +- texinfo -Cross-Compiling Options ------------------------ +USB-based adapters depend on libusb-1.0 and some older drivers require +libusb-0.1 or libusb-compat-0.1. A compatible implementation, such as +FreeBSD's, additionally needs the corresponding .pc files. -To cross-compile, you must specify both --build and --host options to -the 'configure' script. For example, you can configure OpenOCD to -cross-compile on a x86 Linux host to run on Windows (MinGW32), you could -use the following configuration options: +USB-Blaster, ASIX Presto, OpenJTAG and ft2232 interface adapter +drivers need either one of: + - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php + - ftd2xx: http://www.ftdichip.com/Drivers/D2XX.htm (proprietary, + GPL-incompatible) - ./configure --build=i686-pc-linux-gnu --host=i586-mingw32msvc ... +Permissions delegation +---------------------- -Likewise, the following options allow OpenOCD to be cross-compiled for -an ARM target on the same x86 host: +Running OpenOCD with root/administrative permissions is strongly +discouraged for security reasons. - ./configure --build=i686-pc-linux-gnu --host=arm-elf ... +For USB devices on GNU/Linux you should use the contrib/openocd.udev +rules file. It probably belongs somewhere in /etc/udev/rules.d, but +consult your operating system documentation to be sure. Do not forget +to add yourself to the "plugdev" group. -Both must be specified to work around bugs in autoconf. +For parallel port adapters on GNU/Linux and FreeBSD please change your +"ppdev" (parport* or ppi*) device node permissions accordingly. -Scripts for producing ARM cross-compilers can be found on the web with a -little searching. A script to produce an x86 Linux-hosted MinGW32 -cross-compiler can be downloaded from the following URL: - - http://www.mingw.org/wiki/LinuxCrossMinGW - -Configuration Options ---------------------- +For parport adapters on Windows you need to run install_giveio.bat +(it's also possible to use "ioperm" with Cygwin instead) to give +ordinary users permissions for accessing the "LPT" registers directly. -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-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 - - --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] +Compiling OpenOCD +----------------- -Parallel Port Dongles ---------------------- +To build OpenOCD, use the following sequence of commands: -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). + ./bootstrap (when building from the git repository) + ./configure [options] + make + sudo make install -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. +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. -FT2232C Based USB Dongles -------------------------- +To see the list of all the supported options, run + ./configure --help -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. +Cross-compiling Options +----------------------- -Using LIBFTDI -------------- +Cross-compiling is supported the standard autotools way, you just need +to specify the cross-compiling target triplet in the --host option, +e.g. for cross-building for Windows 32-bit with MinGW on Debian: -The libftdi source code can be download from the following website: + ./configure --host=i686-w64-mingw32 [options] - http://www.intra2net.com/en/developer/libftdi/download.php +To make pkg-config work nicely for cross-compiling, you might need an +additional wrapper script as described at -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. + http://www.flameeyes.eu/autotools-mythbuster/pkgconfig/cross-compiling.html -For Windows, libftdi is supported with versions 0.14 and later. +This is needed to tell pkg-config where to look for the target +libraries that OpenOCD depends on. Alternatively, you can specify +*_CFLAGS and *_LIBS environment variables directly, see "./configure +--help" for the details. -With these prerequisites met, configure the libftdi solution like this: +Parallel Port Dongles +--------------------- - ./configure --prefix=/path/for/your/install --enable-ft2232_libftdi +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. -Then type ``make'', and perhaps ``make install''. +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. Using FTDI's FTD2XX ------------------- -The (closed source) FTDICHIP.COM solution is faster on MS-Windows. That -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 (closed source) FTDICHIP.COM solution is faster than libftdi on +Windows. That 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 +TAR.GZ file. You must unpack them ``some where'' convenient. 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: +You should use the following ./configure options to make use of +FTD2XX: --with-ftd2xx-win32-zipdir Where (CYGWIN/MINGW) the zip file from ftdichip.com @@ -348,62 +320,46 @@ If your distribution does not package these, there are several --with-ftd2xx-linux-tardir Where (Linux/Unix) the tar file from ftdichip.com was unpacked - --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 + --with-ftd2xx-lib=(static|shared) + Use static or shared ftd2xx libs (default is static) 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. - -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 ... +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. Note that on Linux there is no good reason to use these FTDI binaries; they are no faster (on Linux) than libftdi, and cause licensing issues. -================================= -Obtaining OpenOCD From Subversion ---------------------------------- -You can download the current SVN version with an SVN client of your -choice from the following repositories: +========================== +Obtaining OpenOCD From GIT +========================== + +You can download the current GIT version with a GIT client of your +choice from the main repository: + + git://git.code.sf.net/p/openocd/code - svn://svn.berlios.de/openocd/trunk -or - http://svn.berlios.de/svnroot/repos/openocd/trunk +You may prefer to use a mirror: -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): + http://repo.or.cz/r/openocd.git + git://repo.or.cz/openocd.git - svn checkout svn://svn.berlios.de/openocd/trunk openocd +Using the GIT command line client, you might use the following command +to set up a local copy of the current repository (make sure there is no +directory called "openocd" in the current directory): -If you prefer GIT based tools, the git-svn package works too: + git clone git://git.code.sf.net/p/openocd/code openocd - git svn clone -s svn://svn.berlios.de/openocd +Then you can update that at your convenience using -Tips For Building From The Subversion Repository -************************************************ + git pull -Building OpenOCD from a repository requires a recent version of the GNU -autotools (autoconf >= 2.59 and automake >= 1.9). +There is also a gitweb interface, which you can use either to browse +the repository or to download arbitrary snapshots using HTTP: -1) Run './bootstrap' to create the 'configure' script and prepare - the build process for your host system. + http://repo.or.cz/w/openocd.git -2) Run './configure --enable-maintainer-mode' with other options. +Snapshots are compressed tarballs of the source tree, about 1.3 MBytes +each at this writing.