X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=README;h=065994a3f85ab1f5c3087db0740404bca4f36e97;hp=d1b983d76aebea4cfbc8391f764f28496cf42c1d;hb=cb6836f9235cd8c57cd08c7cb4121d2328d50155;hpb=ab90b8777855876f23c779ee2b25827a34f890c3 diff --git a/README b/README index d1b983d76a..065994a3f8 100644 --- a/README +++ b/README @@ -2,36 +2,69 @@ 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: + OpenOCD User's Guide: http://openocd.sourceforge.net/doc/html/index.html - OpenOCD Developer's Manual: + 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: @@ -40,7 +73,12 @@ by subscribing to the OpenOCD developer mailing list: 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,24 +90,48 @@ 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 +------------- + +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 +------------- - # If HTMLVIEWER is set, this views the HTML Doxygen output. - ${HTMLVIEWER} doxygen/index.html +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/openocd.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 ----------------------- @@ -77,13 +139,14 @@ If you would rather be working "with" OpenOCD rather than "on" it, your 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. +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,249 +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. - -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. - -Cross-Compiling Options ------------------------ - -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: - - ./configure --build=i686-pc-linux-gnu --host=i586-mingw32msvc ... - -Likewise, the following options allow OpenOCD to be cross-compiled for -an ARM target on the same x86 host: - - ./configure --build=i686-pc-linux-gnu --host=arm-elf ... +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. -Both must be specified to work around bugs in autoconf. +You'll also need: -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: +- make +- libtool +- pkg-config >= 0.23 (or compatible) - http://www.mingw.org/wiki/LinuxCrossMinGW +Additionally, for building from git: -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-dummy Enable building the dummy JTAG port driver - - --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-ftdi Enable building support for the MPSSE mode of FTDI - based devices, using libusb-1.0 in asynchronous mode - - --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-usb_blaster_libftdi - Enable building support for the Altera USB-Blaster - using the libftdi driver, opensource alternate of - FTD2XX - --enable-usb_blaster_ftd2xx - Enable building support for the Altera USB-Blaster - using the FTD2XX driver from ftdichip.com - - --enable-amtjtagaccel Enable building the Amontec JTAG-Accelerator driver - - --enable-zy1000-master Use ZY1000 JTAG master registers - --enable-zy1000 Enable ZY1000 interface - - --enable-ioutil Enable ioutil functions - useful for standalone - OpenOCD implementations +- autoconf >= 2.64 +- automake >= 1.9 +- texinfo - --enable-ep93xx Enable building support for EP93xx based SBCs +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. - --enable-at91rm9200 Enable building support for AT91RM9200 based SBCs +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) - --enable-gw16012 Enable building support for the Gateworks GW16012 - JTAG Programmer +Permissions delegation +---------------------- - --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 +Running OpenOCD with root/administrative permissions is strongly +discouraged for security reasons. - --enable-usbprog Enable building support for the usbprog JTAG - Programmer +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. - --enable-oocd_trace Enable building support for some prototype - OpenOCD+trace ETM capture hardware +For parallel port adapters on GNU/Linux and FreeBSD please change your +"ppdev" (parport* or ppi*) device node permissions accordingly. - --enable-jlink Enable building support for the Segger J-Link JTAG - Programmer +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. - --enable-vsllink Enable building support for the Versaloon-Link JTAG - Programmer - - --enable-rlink Enable building support for the Raisonance RLink - JTAG Programmer - --enable-ulink Enable building support for the Keil ULINK JTAG - Programmer - --enable-arm-jtag-ew Enable building support for the Olimex ARM-JTAG-EW - Programmer - - --enable-buspirate Enable building support for the Buspirate - - --enable-stlink Enable building support for the ST-Link JTAG - Programmer - --enable-ti-icdi Enable building support for the TI/Stellaris ICDI - JTAG Programmer - - --enable-osbdm Enable building support for the OSBDM (JTAG only) - Programmer - - --enable-opendous Enable building support for the estick/opendous JTAG - Programmer - --enable-sysfsgpio Enable building support for programming driven via - sysfs gpios. +Compiling OpenOCD +----------------- - --enable-minidriver-dummy - Enable the dummy minidriver. +To build OpenOCD, use the following sequence of commands: - --disable-internal-jimtcl - Disable building internal jimtcl + ./bootstrap (when building from the git repository) + ./configure [options] + make + sudo make install - --enable-remote-bitbang Enable building support for the Remote Bitbang jtag - driver +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. - --disable-doxygen-html Disable building Doxygen manual as HTML. - --enable-doxygen-pdf Enable building Doxygen manual as PDF. +To see the list of all the supported options, run + ./configure --help -Miscellaneous Configure Options -------------------------------- +Cross-compiling Options +----------------------- -The following additional options may also be useful: +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: - --disable-assert turn off assertions + ./configure --host=i686-w64-mingw32 [options] - --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). +To make pkg-config work nicely for cross-compiling, you might need an +additional wrapper script as described at - --disable-gccwarnings Disable extra gcc warnings during build. - --disable-wextra Disable extra compiler warnings - --disable-werror Do not treat warnings as errors + http://www.flameeyes.eu/autotools-mythbuster/pkgconfig/cross-compiling.html - --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] +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. 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 later option is an option to the parport driver. -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 +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 -------------- - -The libftdi source code can be download from the following website: - - http://www.intra2net.com/en/developer/libftdi/download.php - -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), use libftdi version 0.17 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 ------------------- -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'' 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 @@ -383,34 +320,18 @@ 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 GIT ========================== @@ -442,15 +363,3 @@ the repository or to download arbitrary snapshots using HTTP: Snapshots are compressed tarballs of the source tree, about 1.3 MBytes each at this writing. - - -Tips For Building From a GIT Repository ---------------------------------------- - -Building OpenOCD from a repository requires a recent version of the GNU -autotools (autoconf >= 2.60 and automake >= 1.9). - -1) Run './bootstrap' to create the 'configure' script and prepare - the build process for your host system. - -2) Run './configure' with other options.