Convert to non-recursive make
[openocd.git] / README
diff --git a/README b/README
index c6186b2..615ae81 100644 (file)
--- a/README
+++ b/README
@@ -2,36 +2,70 @@ 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 -c "transport select jtag" \
+          -f target/ti_calypso.cfg
+
+  openocd -f interface/stlink-v2-1.cfg -c "transport select hla_swd" \
+          -f target/stm32l0.cfg
+
+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.sourceforge.net/doc/html/index.html
 OpenOCD User's Guide:
+    http://openocd.org/doc/html/index.html
 
- OpenOCD Developer's Manual:
-    http://openocd.sourceforge.net/doc/doxygen/html/index.html
 OpenOCD Developer's Manual:
+    http://openocd.org/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 +74,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 +91,49 @@ 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
 
-  # If HTMLVIEWER is set, this views the HTML Doxygen output.
-  ${HTMLVIEWER} doxygen/index.html
 
-The remaining sections describe how to configure the system such that
-you can build the in-tree documentation.
+==================
+Supported hardware
+==================
+
+JTAG adapters
+-------------
+
+AICE, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432,
+BCM2835, Bus Blaster, Buspirate, Chameleon, CMSIS-DAP, Cortino, DENX,
+Digilent JTAG-SMT2, 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, LS102x-SAP,
+Feroceon/Dragonite, DSP563xx, DSP5680xx, FA526, MIPS EJTAG, NDS32,
+XScale, Intel Quark.
+
+Flash drivers
+-------------
+
+ADUC702x, AT91SAM, AVR, CFI, DSP5680xx, EFM32, EM357, FM3, FM4, Kinetis,
+LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPCSPIFI, Marvell QSPI,
+Milandr, NIIET, NuMicro, PIC32mx, PSoC4, SiM3x, Stellaris, STM32, STMSMI,
+STR7x, STR9x, nRF51; NAND controllers of AT91SAM9, LPC3180, LPC32xx,
+i.MX31, MXC, NUC910, Orion/Kirkwood, S3C24xx, S3C6400, XMC1xxx, XMC4xxx.
+
 
 ==================
 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 +141,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 +159,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 +175,21 @@ 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.
 
-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,250 +197,104 @@ 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:
+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.
 
-   ./configure [with some options listed in the next section]
-   make
-   make install
+You'll also need:
 
-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.
+- make
+- libtool
+- pkg-config >= 0.23 (or compatible)
 
-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 ...
-
-Both must be specified to work around bugs in autoconf.
-
-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
+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-maintainer-mode  enable make rules and dependencies not useful
-                          (and sometimes confusing) to the casual installer
-                         NOTE: This option is *required* for GIT 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-ulink          Enable building support for the Keil ULINK 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-zy1000         Enable ZY1000 interface
-
-  --enable-minidriver-dummy
-                          Enable the dummy minidriver.
-
-  --enable-ioutil         Enable ioutil functions - useful for standalone
-                          OpenOCD implementations
-
-  --disable-doxygen-html Disable building Doxygen manual as HTML.
-  --enable-doxygen-pdf   Enable building Doxygen manual as PDF.
-
-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]
+- autoconf >= 2.64
+- automake >= 1.14
+- texinfo
 
-Parallel Port Dongles
----------------------
+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.
 
-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).
+USB-Blaster, ASIX Presto and OpenJTAG interface adapter
+drivers need:
+  - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php
 
-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.
+CMSIS-DAP support needs HIDAPI library.
 
-FT2232C Based USB Dongles
--------------------------
+Permissions delegation
+----------------------
 
-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.
+Running OpenOCD with root/administrative permissions is strongly
+discouraged for security reasons.
 
-Using LIBFTDI
--------------
+For USB devices on GNU/Linux you should use the contrib/99-openocd.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.
 
-The libftdi source code can be download from the following website:
+For parallel port adapters on GNU/Linux and FreeBSD please change your
+"ppdev" (parport* or ppi*) device node permissions accordingly.
 
-  http://www.intra2net.com/en/developer/libftdi/download.php
+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.
 
-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:
+Compiling OpenOCD
+-----------------
 
-  ./configure --prefix=/path/for/your/install --enable-ft2232_libftdi
+To build OpenOCD, use the following sequence of commands:
 
-Then type ``make'', and perhaps ``make install''.
+  ./bootstrap (when building from the git repository)
+  ./configure [options]
+  make
+  sudo make install
 
-Using FTDI's FTD2XX
--------------------
+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.
 
-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.
+To see the list of all the supported options, run
+  ./configure --help
 
-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."
+Cross-compiling Options
+-----------------------
 
-If your distribution does not package these, there are several
-'./configure' options to solve this problem:
+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:
 
-  --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
+  ./configure --host=i686-w64-mingw32 [options]
 
-If you are using the FTDICHIP.COM driver, download and unpack the
-Windows or Linux FTD2xx drivers from the following location:
+To make pkg-config work nicely for cross-compiling, you might need an
+additional wrapper script as described at
 
-       http://www.ftdichip.com/Drivers/D2XX.htm
+  http://www.flameeyes.eu/autotools-mythbuster/pkgconfig/cross-compiling.html
 
-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.
+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.
 
-Linux Notes
-***********
+Parallel Port Dongles
+---------------------
 
-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:
+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.
 
-   ./configure \
-        --enable-ft2232_ftd2xx \
-        --with-ft2xx-linux-tardir=../libftd2xx0.4.16 \
-       ... other options ...
+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.
 
-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
@@ -385,7 +303,7 @@ Obtaining OpenOCD From GIT
 You can download the current GIT version with a GIT client of your
 choice from the main repository:
 
-   git://openocd.git.sourceforge.net/gitroot/openocd/openocd
+   git://git.code.sf.net/p/openocd/code
 
 You may prefer to use a mirror:
 
@@ -396,7 +314,7 @@ 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):
 
-   git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd
+   git clone git://git.code.sf.net/p/openocd/code openocd
 
 Then you can update that at your convenience using
 
@@ -405,20 +323,7 @@ Then you can update that at your convenience using
 There is also a gitweb interface, which you can use either to browse
 the repository or to download arbitrary snapshots using HTTP:
 
-   http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd
    http://repo.or.cz/w/openocd.git
 
 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.59 and automake >= 1.9).
-
-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.