README

   1                                     OpenOCD
   2
   3                          Free and Open On-Chip Debugging, In-System Programming
   4                                                    and Boundary-Scan Testing
   5                                   Copyright (c) 2004-2007 Dominic Rath
   6
   7 The debugger uses an IEEE 1149-1 compliant JTAG TAP bus master to access on-chip
   8 debug functionality available on ARM7 and ARM9 based microcontrollers /
   9 system-on-chip solutions.
  10
  11 User interaction is realized through a telnet command line interface and a gdb
  12 (The GNU Debugger) remote protocol server.
  13
  14 1. JTAG hardware
  15
  16 Currently, OpenOCD supports the following JTAG interfaces:
  17
  18 - Parallel port wigglers. These devices connect to a PC's parallel port,
  19 providing direct access to the JTAG lines. The OpenOCD contains descriptions
  20 of a few Wiggler layouts, including the original 'Wiggler' design. Other
  21 layouts (i.e. mapping of parallel port pins to JTAG lines) can be added easily.
  22 Typical Wiggler speeds are around 12kByte/s code download to an ARM7's RAM.
  23
  24 The list of supported parallel port devices includes:
  25
  26   * Macraigor Wiggler JTAG cable
  27   * Gateworks GW16012 JTAG programmer
  28   * Xilinx DLC5 JTAG parallel cable III
  29   * Ka-Ro TRITON starterkit II JTAG cable
  30   * Lattice parallel port JTAG cable
  31   * ST FlashLINK programming cable
  32   * Wiggler 2 cable (basically a wiggler with an LED)
  33
  34 - The Amontec JTAG Accelerator. This is a configuration for Amontec's Chameleon
  35 dongle, a parallel port interface based on a Xilinx CoolRunner CPLD. It uses
  36 the IEEE1284 EPP parallel port specification, providing many times the
  37 performance achievable with wiggler-style devices. Additional information is
  38 available on www.amontec.com.
  39 Typical JTAG Accelerator speeds are around 120-160kByte/s to an ARM7's RAM.
  40
  41 - FTDI FT2232 based USB devices. The FT2232 (but not FT232 or FT245) features a
  42 multi-protocol synchronous serial engine (MPSSE) that can be used to run the
  43 serial JTAG protocol. There are several implemenations of FT2232 based devices:
  44
  45 * USBJTAG: http://www.fh-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html
  46 The USBJTAG was designed by Prof. Hubert Hoegl to provide a high-speed USB
  47 interface for use with the OpenOCD. Schematics are available at the USBJTAG
  48 website, and a homebrew device can easily be built using the FTDI evaluation
  49 module DLP2232M.
  50
  51 * OOCD-Link: http://www.joernonline.de/dw/doku.php?id=en:projects:oocdlink
  52 Similar to the USBJTAG, this design comes with free schematics, too.
  53
  54 * Amontec JTAGkey: www.amontec.com
  55 The Amontec JTAGkey offers support for a wide variety of target voltages from
  56 1.4V to 5V. It also allows the JTAG lines and reset signals to be tri-stated,
  57 allowing easy interfacing with a wide variety of targets.
  58
  59 * Amontec JTAGkey-Tiny: www.amontec.com
  60 The Amontec JTAGkey offers support for a wide variety of target voltages from
  61 2.8V to 5V. It also allows the reset signals to be tri-stated, allowing easy
  62 interfacing with a wide variety of targets.
  63
  64 * Olimex ARM-USB-OCD: www.olimex.com
  65 The Olimex ARM-USB-OCD offers support for a wide vriety of target voltages from
  66 2.0V to 5V. It also allows targets to be powered from the ARM-USB-OCD and
  67 features and additional RS232 UART.
  68
  69 * eVerve Signalyzer: www.signalyzer.com
  70 The Signalyzer offers support for a wide variety of target voltages from 1.2V to
  71 5.5V. A second connector provides access to a TTL level UART.
  72
  73 * TinCanTools 'Flyswatter' USB JTAG programmer.
  74
  75 * Turtelizer 2: http://www.ethernut.de/en/hardware/turtelizer/index.html
  76 Another USB JTAG programmer, with freely available schematics. It supports
  77 target voltages from 1.65V to 5.5V.
  78
  79 * Hitex STR9-comStick: http://www.ehitex.de/p_info.php?products_id=292
  80 A STR912FW44x microcontroller "board" with USB and JTAG functionality.
  81
  82 * Hitex STM32-PerformanceStick: http://www.hitex.com/stm32-stick/
  83 A STM32F103RBT6 microcontroller "board" with USB and JTAG functionality.
  84
  85 * Luminary Micro development board evb_lm3s811 JTAG interface.
  86
  87 * ASIX PRESTO: http://www.asix-tools.com/prg_presto.htm
  88 The ASIX PRESTO is a USB JTAG programmer for a wide range of components, e.g.
  89 microcontrollers, serial EEPROM and Flash memory chips, CPLDs and others.
  90
  91 * usbprog: http://www.embedded-projects.net/index.php?page_id=165
  92 The usbprog is a freely programmable USB adapter, which can (among other
  93 things) use a firmware which turns it into a JTAG programmer/debugger.
  94
  95 * Altium universal JTAG cable
  96
  97 All FT2232 based devices may be accessed using either FTDI's proprietary FTD2XX
  98 library (www.ftdichip.com) or using an open-source replacement from
  99 http://www.intra2net.com/de/produkte/opensource/ftdi/index.php, also included
 100 with many Linux distributions.
 101
 102 2. Supported cores
 103
 104 This version of openocd supports the following ARM7/9 cores:
 105
 106 - ARM7TDMI(-s)
 107 - ARM9TDMI
 108 - ARM920t
 109 - ARM922t
 110 - ARM926ej-s
 111 - ARM966e
 112 - Cortex-M3
 113
 114 Support for Intel XScale CPUs is also included:
 115
 116 - PXA25x
 117 - PXA27x
 118 - IXP42x
 119
 120 And support for the Marvell Feroceon CPU core as found in the
 121 Orion SoC family is included as well.
 122
 123 3. Host platforms
 124
 125 OpenOCD was originally developed on x86-Linux, but has since then been ported
 126 to run on Windows/Cygwin, native Windows with MinGW, FreeBSD, IA64-Linux,
 127 AMD64-Linux, Alpha-Linux, ARM-Linux, and PowerPC OS-X.
 128
 129 4. Documentation
 130
 131 Documentation for the OpenOCD is hosted in the Berlios OpenFacts Wiki at
 132 http://openfacts.berlios.de/index-en.phtml?title=Open_On-Chip_Debugger.
 133
 134 There is also and openocd(1) manpage, the 'openocd --help' output and
 135 an OpenOCD info page (type 'info openocd').
 136
 137 5. Coding Style
 138
 139 The following rules try to describe formatting and naming conventions that
 140 should be followed to make the whole OpenOCD code look more consistent.
 141 The ultimate goal of coding style should be readability, and these rules may
 142 be ignored for a particular (small) piece of code if that makes it more
 143 readable.
 144
 145 Formatting rules:
 146 - remove any trailing white space
 147 - use TAB characters for indentation, not spaces
 148 - displayed TAB width is 4 characters
 149 - make sure NOT to use DOS '\r\n' line feeds
 150 - do not add more than 2 empty lines to source files
 151 - do not add trailing empty lines to source files
 152 - do not use C++ style comments (//)
 153 - lines may be reasonably wide - there's no anachronistic 80 characters limit
 154
 155 Naming rules:
 156 - identifiers use lower-case letters only
 157 - identifiers consisting of multiple words use underline characters between
 158 consecutive words
 159 - macros use upper-case letters only
 160 - structure names shall be appended with '_s'
 161 - typedefs shall be appended with '_t'
 162
 163 Function calls:
 164 - function calls have no space between the functions name and the parameter
 165 list: my_func(param1, param2, ...)
 166
 167 6. Licensing
 168
 169 OpenOCD is licensed under the terms of the GNU General Public License, see the
 170 file COPYING for details.
 171