X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=README;h=34dac0b1b583be41927768178a669c436f7b3b9b;hp=0d0a7e2b3204d1533e4b1db347bcc97bb9551a93;hb=d796f5929c3b2baafae4b8bf27d2b1b71c49ee53;hpb=64dbef69e73714208e791958fff060c4fc7960e2 diff --git a/README b/README index 0d0a7e2b32..34dac0b1b5 100644 --- a/README +++ b/README @@ -1,171 +1,339 @@ - OpenOCD +Welcome to OpenOCD! +=================== - Free and Open On-Chip Debugging, In-System Programming - and Boundary-Scan Testing - Copyright (c) 2004-2007 Dominic Rath +OpenOCD provides on-chip programming and debugging support with a +layered architecture of JTAG interface and TAP support including: -The debugger uses an IEEE 1149-1 compliant JTAG TAP bus master to access on-chip -debug functionality available on ARM7 and ARM9 based microcontrollers / -system-on-chip solutions. +- (X)SVF playback to facilitate 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. -User interaction is realized through a telnet command line interface and a gdb -(The GNU Debugger) remote protocol server. +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). -1. JTAG hardware +This README file contains an overview of the following topics: -Currently, OpenOCD supports the following JTAG interfaces: +- quickstart instructions, +- how to find and build more OpenOCD documentation, +- list of the supported hardware, +- the installation and build process, +- packaging tips. -- Parallel port wigglers. These devices connect to a PC's parallel port, -providing direct access to the JTAG lines. The OpenOCD contains descriptions -of a few Wiggler layouts, including the original 'Wiggler' design. Other -layouts (i.e. mapping of parallel port pins to JTAG lines) can be added easily. -Typical Wiggler speeds are around 12kByte/s code download to an ARM7's RAM. -The list of supported parallel port devices includes: +============================ +Quickstart for the impatient +============================ - * Macraigor Wiggler JTAG cable - * Gateworks GW16012 JTAG programmer - * Xilinx DLC5 JTAG parallel cable III - * Ka-Ro TRITON starterkit II JTAG cable - * Lattice parallel port JTAG cable - * ST FlashLINK programming cable - * Wiggler 2 cable (basically a wiggler with an LED) +If you have a popular board then just start OpenOCD with its config, +e.g.: -- The Amontec JTAG Accelerator. This is a configuration for Amontec's Chameleon -dongle, a parallel port interface based on a Xilinx CoolRunner CPLD. It uses -the IEEE1284 EPP parallel port specification, providing many times the -performance achievable with wiggler-style devices. Additional information is -available on www.amontec.com. -Typical JTAG Accelerator speeds are around 120-160kByte/s to an ARM7's RAM. + openocd -f board/stm32f4discovery.cfg -- FTDI FT2232 based USB devices. The FT2232 (but not FT232 or FT245) features a -multi-protocol synchronous serial engine (MPSSE) that can be used to run the -serial JTAG protocol. There are several implemenations of FT2232 based devices: +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.: -* USBJTAG: http://www.fh-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html -The USBJTAG was designed by Prof. Hubert Hoegl to provide a high-speed USB -interface for use with the OpenOCD. Schematics are available at the USBJTAG -website, and a homebrew device can easily be built using the FTDI evaluation -module DLP2232M. + openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \ + -f target/ti_calypso.cfg -* OOCD-Link: http://www.joernonline.de/dw/doku.php?id=en:projects:oocdlink -Similar to the USBJTAG, this design comes with free schematics, too. + openocd -f interface/stlink.cfg -c "transport select hla_swd" \ + -f target/stm32l0.cfg -* Amontec JTAGkey: www.amontec.com -The Amontec JTAGkey offers support for a wide variety of target voltages from -1.4V to 5V. It also allows the JTAG lines and reset signals to be tri-stated, -allowing easy interfacing with a wide variety of targets. +After OpenOCD startup, connect GDB with -* Amontec JTAGkey-Tiny: www.amontec.com -The Amontec JTAGkey offers support for a wide variety of target voltages from -2.8V to 5V. It also allows the reset signals to be tri-stated, allowing easy -interfacing with a wide variety of targets. + (gdb) target extended-remote localhost:3333 -* Olimex ARM-USB-OCD: www.olimex.com -The Olimex ARM-USB-OCD offers support for a wide vriety of target voltages from -2.0V to 5V. It also allows targets to be powered from the ARM-USB-OCD and -features and additional RS232 UART. -* eVerve Signalyzer: www.signalyzer.com -The Signalyzer offers support for a wide variety of target voltages from 1.2V to -5.5V. A second connector provides access to a TTL level UART. +===================== +OpenOCD Documentation +===================== -* TinCanTools 'Flyswatter' USB JTAG programmer. +In addition to the in-tree documentation, the latest manuals may be +viewed online at the following URLs: -* Turtelizer 2: http://www.ethernut.de/en/hardware/turtelizer/index.html -Another USB JTAG programmer, with freely available schematics. It supports -target voltages from 1.65V to 5.5V. + OpenOCD User's Guide: + http://openocd.org/doc/html/index.html -* Hitex STR9-comStick: http://www.ehitex.de/p_info.php?products_id=292 -A STR912FW44x microcontroller "board" with USB and JTAG functionality. + OpenOCD Developer's Manual: + http://openocd.org/doc/doxygen/html/index.html -* Hitex STM32-PerformanceStick: http://www.hitex.com/stm32-stick/ -A STM32F103RBT6 microcontroller "board" with USB and JTAG functionality. +These reflect the latest development versions, so the following section +introduces how to build the complete documentation from the package. -* Luminary Micro development board evb_lm3s811 JTAG interface. +For more information, refer to these documents or contact the developers +by subscribing to the OpenOCD developer mailing list: -* ASIX PRESTO: http://www.asix-tools.com/prg_presto.htm -The ASIX PRESTO is a USB JTAG programmer for a wide range of components, e.g. -microcontrollers, serial EEPROM and Flash memory chips, CPLDs and others. + openocd-devel@lists.sourceforge.net -* usbprog: http://www.embedded-projects.net/index.php?page_id=165 -The usbprog is a freely programmable USB adapter, which can (among other -things) use a firmware which turns it into a JTAG programmer/debugger. +Building the OpenOCD Documentation +---------------------------------- -* Altium universal JTAG cable +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. -All FT2232 based devices may be accessed using either FTDI's proprietary FTD2XX -library (www.ftdichip.com) or using an open-source replacement from -http://www.intra2net.com/de/produkte/opensource/ftdi/index.php, also included -with many Linux distributions. +Additionally, the OpenOCD User's Guide can be produced in the +following different formats: -2. Supported cores + # If PDFVIEWER is set, this creates and views the PDF User Guide. + make pdf && ${PDFVIEWER} doc/openocd.pdf -This version of openocd supports the following ARM7/9 cores: + # If HTMLVIEWER is set, this creates and views the HTML User Guide. + make html && ${HTMLVIEWER} doc/openocd.html/index.html -- ARM7TDMI(-s) -- ARM9TDMI -- ARM920t -- ARM922t -- ARM926ej-s -- ARM966e -- Cortex-M3 +The OpenOCD Developer Manual contains information about the internal +architecture and other details about the code: -Support for Intel XScale CPUs is also included: + # NB! make sure doxygen is installed, type doxygen --version + make doxygen && ${HTMLVIEWER} doxygen/index.html -- PXA25x -- PXA27x -- IXP42x -And support for the Marvell Feroceon CPU core as found in the -Orion SoC family is included as well. +================== +Supported hardware +================== -3. Host platforms +JTAG adapters +------------- -OpenOCD was originally developed on x86-Linux, but has since then been ported -to run on Windows/Cygwin, native Windows with MinGW, FreeBSD, IA64-Linux, -AMD64-Linux, Alpha-Linux, ARM-Linux, and PowerPC OS-X. +AICE, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835, +Bus Blaster, Buspirate, Cadence DPI, Chameleon, CMSIS-DAP, Cortino, +Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H, +embedded projects, eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2, +FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey, +JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick, +Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO, +OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee, +Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits, +ST-LINK (SWO tracing supported), STM32-PerformanceStick, STR9-comStick, +sysfsgpio, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster, +USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe, +Xverve. -4. Documentation +Debug targets +------------- -Documentation for the OpenOCD is hosted in the Berlios OpenFacts Wiki at -http://openfacts.berlios.de/index-en.phtml?title=Open_On-Chip_Debugger. +ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M), +FA526, Feroceon/Dragonite, XScale. +ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64), +Intel Quark, LS102x-SAP, NDS32, RISC-V, ST STM8. -There is also and openocd(1) manpage, the 'openocd --help' output and -an OpenOCD info page (type 'info openocd'). +Flash drivers +------------- -5. Coding Style +ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI, +DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI, +i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx, +LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro, +NUC910, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6, Renesas RPC HF and SH QSPI, +S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32, +STM32 QUAD/OCTO-SPI for Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050, +TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF, +XMC1xxx, XMC4xxx. -The following rules try to describe formatting and naming conventions that -should be followed to make the whole OpenOCD code look more consistent. -The ultimate goal of coding style should be readability, and these rules may -be ignored for a particular (small) piece of code if that makes it more -readable. -Formatting rules: -- remove any trailing white space -- use TAB characters for indentation, not spaces -- displayed TAB width is 4 characters -- make sure NOT to use DOS '\r\n' line feeds -- do not add more than 2 empty lines to source files -- do not add trailing empty lines to source files -- do not use C++ style comments (//) -- lines may be reasonably wide - there's no anachronistic 80 characters limit +================== +Installing OpenOCD +================== -Naming rules: -- identifiers use lower-case letters only -- identifiers consisting of multiple words use underline characters between -consecutive words -- macros use upper-case letters only -- structure names shall be appended with '_s' -- typedefs shall be appended with '_t' +A Note to OpenOCD Users +----------------------- -Function calls: -- function calls have no space between the functions name and the parameter -list: my_func(param1, param2, ...) +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. -6. Licensing +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. -OpenOCD is licensed under the terms of the GNU General Public License, see the -file COPYING for details. +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 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 +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, 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. + + +================ +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 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. + +OpenOCD Dependencies +-------------------- + +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. + +You'll also need: + +- make +- libtool +- pkg-config >= 0.23 (or compatible) + +Additionally, for building from git: + +- autoconf >= 2.69 +- automake >= 1.14 +- texinfo >= 5.0 + +USB-based adapters depend on libusb-1.0. A compatible implementation, such as +FreeBSD's, additionally needs the corresponding .pc files. + +USB-Blaster, ASIX Presto and OpenJTAG interface adapter +drivers need: + - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php + +CMSIS-DAP support needs HIDAPI library. + +Permissions delegation +---------------------- + +Running OpenOCD with root/administrative permissions is strongly +discouraged for security reasons. + +For USB devices on GNU/Linux you should use the contrib/60-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. + +For parallel port adapters on GNU/Linux and FreeBSD please change your +"ppdev" (parport* or ppi*) device node permissions accordingly. + +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. + +Compiling OpenOCD +----------------- + +To build OpenOCD, use the following sequence of commands: + + ./bootstrap (when building from the git repository) + ./configure [options] + make + sudo 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. + +To see the list of all the supported options, run + ./configure --help + +Cross-compiling Options +----------------------- + +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: + + ./configure --host=i686-w64-mingw32 [options] + +To make pkg-config work nicely for cross-compiling, you might need an +additional wrapper script as described at + + https://autotools.io/pkgconfig/cross-compiling.html + +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. + +For a more or less complete script that does all this for you, see + + contrib/cross-build.sh + +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 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 +method. + + +========================== +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 + +You may prefer to use a mirror: + + http://repo.or.cz/r/openocd.git + git://repo.or.cz/openocd.git + +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://git.code.sf.net/p/openocd/code openocd + +Then you can update that at your convenience using + + git pull + +There is also a gitweb interface, which you can use either to browse +the repository or to download arbitrary snapshots using HTTP: + + http://repo.or.cz/w/openocd.git + +Snapshots are compressed tarballs of the source tree, about 1.3 MBytes +each at this writing.