+
+@item @b{Wiggler} - There are many clones of this.
+@* Link: @url{http://www.macraigor.com/wiggler.htm}
+
+@item @b{DLC5} - From XILINX - There are many clones of this
+@* Link: Search the web for: ``XILINX DLC5'' - it is no longer
+produced, PDF schematics are easily found and it is easy to make.
+
+@item @b{Amontec - JTAG Accelerator}
+@* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
+
+@item @b{GW16402}
+@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
+
+@item @b{Wiggler2}
+@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
+Improved parallel-port wiggler-style JTAG adapter}
+
+@item @b{Wiggler_ntrst_inverted}
+@* Yet another variation - See the source code, src/jtag/parport.c
+
+@item @b{old_amt_wiggler}
+@* Unknown - probably not on the market today
+
+@item @b{arm-jtag}
+@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
+
+@item @b{chameleon}
+@* Link: @url{http://www.amontec.com/chameleon.shtml}
+
+@item @b{Triton}
+@* Unknown.
+
+@item @b{Lattice}
+@* ispDownload from Lattice Semiconductor
+@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
+
+@item @b{flashlink}
+@* From ST Microsystems;
+@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
+FlashLINK JTAG programing cable for PSD and uPSD}
+
+@end itemize
+
+@section Other...
+@itemize @bullet
+
+@item @b{ep93xx}
+@* An EP93xx based Linux machine using the GPIO pins directly.
+
+@item @b{at91rm9200}
+@* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.
+
+@end itemize
+
+@node About JIM-Tcl
+@chapter About JIM-Tcl
+@cindex JIM Tcl
+@cindex tcl
+
+OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
+This programming language provides a simple and extensible
+command interpreter.
+
+All commands presented in this Guide are extensions to JIM-Tcl.
+You can use them as simple commands, without needing to learn
+much of anything about Tcl.
+Alternatively, can write Tcl programs with them.
+
+You can learn more about JIM at its website, @url{http://jim.berlios.de}.
+
+@itemize @bullet
+@item @b{JIM vs. Tcl}
+@* JIM-TCL is a stripped down version of the well known Tcl language,
+which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
+fewer features. JIM-Tcl is a single .C file and a single .H file and
+implements the basic Tcl command set. In contrast: Tcl 8.6 is a
+4.2 MB .zip file containing 1540 files.
+
+@item @b{Missing Features}
+@* Our practice has been: Add/clone the real Tcl feature if/when
+needed. We welcome JIM Tcl improvements, not bloat.
+
+@item @b{Scripts}
+@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
+command interpreter today is a mixture of (newer)
+JIM-Tcl commands, and (older) the orginal command interpreter.
+
+@item @b{Commands}
+@* At the OpenOCD telnet command line (or via the GDB mon command) one
+can type a Tcl for() loop, set variables, etc.
+Some of the commands documented in this guide are implemented
+as Tcl scripts, from a @file{startup.tcl} file internal to the server.
+
+@item @b{Historical Note}
+@* JIM-Tcl was introduced to OpenOCD in spring 2008.
+
+@item @b{Need a crash course in Tcl?}
+@*@xref{Tcl Crash Course}.
+@end itemize
+
+@node Running
+@chapter Running
+@cindex command line options
+@cindex logfile
+@cindex directory search
+
+The @option{--help} option shows:
+@verbatim
+bash$ openocd --help
+
+--help | -h display this help
+--version | -v display OpenOCD version
+--file | -f use configuration file <name>
+--search | -s dir to search for config files and scripts
+--debug | -d set debug level <0-3>
+--log_output | -l redirect log output to file <name>
+--command | -c run <command>
+--pipe | -p use pipes when talking to gdb
+@end verbatim
+
+By default OpenOCD reads the file configuration file @file{openocd.cfg}
+in the current directory. To specify a different (or multiple)
+configuration file, you can use the ``-f'' option. For example:
+
+@example
+openocd -f config1.cfg -f config2.cfg -f config3.cfg
+@end example
+
+OpenOCD starts by processing the configuration commands provided
+on the command line or in @file{openocd.cfg}.
+@xref{Configuration Stage}.
+At the end of the configuration stage it verifies the JTAG scan
+chain defined using those commands; your configuration should
+ensure that this always succeeds.
+Normally, OpenOCD then starts running as a daemon.
+Alternatively, commands may be used to terminate the configuration
+stage early, perform work (such as updating some flash memory),
+and then shut down without acting as a daemon.
+
+Once OpenOCD starts running as a daemon, it waits for connections from
+clients (Telnet, GDB, Other) and processes the commands issued through
+those channels.
+
+If you are having problems, you can enable internal debug messages via
+the ``-d'' option.
+
+Also it is possible to interleave JIM-Tcl commands w/config scripts using the
+@option{-c} command line switch.
+
+To enable debug output (when reporting problems or working on OpenOCD
+itself), use the @option{-d} command line switch. This sets the
+@option{debug_level} to "3", outputting the most information,
+including debug messages. The default setting is "2", outputting only
+informational messages, warnings and errors. You can also change this
+setting from within a telnet or gdb session using @command{debug_level
+<n>} (@pxref{debug_level}).
+
+You can redirect all output from the daemon to a file using the
+@option{-l <logfile>} switch.
+
+Search paths for config/script files can be added to OpenOCD by using
+the @option{-s <search>} switch. The current directory and the OpenOCD
+target library is in the search path by default.
+
+For details on the @option{-p} option. @xref{Connecting to GDB}.
+
+Note! OpenOCD will launch the GDB & telnet server even if it can not
+establish a connection with the target. In general, it is possible for
+the JTAG controller to be unresponsive until the target is set up
+correctly via e.g. GDB monitor commands in a GDB init script.
+
+@node OpenOCD Project Setup
+@chapter OpenOCD Project Setup
+
+To use OpenOCD with your development projects, you need to do more than
+just connecting the JTAG adapter hardware (dongle) to your development board
+and then starting the OpenOCD server.
+You also need to configure that server so that it knows
+about that adapter and board, and helps your work.
+
+@section Hooking up the JTAG Adapter
+
+Today's most common case is a dongle with a JTAG cable on one side
+(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
+and a USB cable on the other.
+Instead of USB, some cables use Ethernet;
+older ones may use a PC parallel port, or even a serial port.
+
+@enumerate
+@item @emph{Start with power to your target board turned off},
+and nothing connected to your JTAG adapter.
+If you're particularly paranoid, unplug power to the board.
+It's important to have the ground signal properly set up,
+unless you are using a JTAG adapter which provides
+galvanic isolation between the target board and the
+debugging host.
+
+@item @emph{Be sure it's the right kind of JTAG connector.}
+If your dongle has a 20-pin ARM connector, you need some kind
+of adapter (or octopus, see below) to hook it up to
+boards using 14-pin or 10-pin connectors ... or to 20-pin
+connectors which don't use ARM's pinout.
+
+In the same vein, make sure the voltage levels are compatible.
+Not all JTAG adapters have the level shifters needed to work
+with 1.2 Volt boards.
+
+@item @emph{Be certain the cable is properly oriented} or you might
+damage your board. In most cases there are only two possible
+ways to connect the cable.
+Connect the JTAG cable from your adapter to the board.
+Be sure it's firmly connected.
+
+In the best case, the connector is keyed to physically
+prevent you from inserting it wrong.
+This is most often done using a slot on the board's male connector
+housing, which must match a key on the JTAG cable's female connector.
+If there's no housing, then you must look carefully and
+make sure pin 1 on the cable hooks up to pin 1 on the board.
+Ribbon cables are frequently all grey except for a wire on one
+edge, which is red. The red wire is pin 1.
+
+Sometimes dongles provide cables where one end is an ``octopus'' of
+color coded single-wire connectors, instead of a connector block.
+These are great when converting from one JTAG pinout to another,
+but are tedious to set up.
+Use these with connector pinout diagrams to help you match up the
+adapter signals to the right board pins.
+
+@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
+A USB, parallel, or serial port connector will go to the host which
+you are using to run OpenOCD.
+For Ethernet, consult the documentation and your network administrator.
+
+For USB based JTAG adapters you have an easy sanity check at this point:
+does the host operating system see the JTAG adapter?
+
+@item @emph{Connect the adapter's power supply, if needed.}
+This step is primarily for non-USB adapters,
+but sometimes USB adapters need extra power.
+
+@item @emph{Power up the target board.}
+Unless you just let the magic smoke escape,
+you're now ready to set up the OpenOCD server
+so you can use JTAG to work with that board.
+
+@end enumerate
+
+Talk with the OpenOCD server using
+telnet (@code{telnet localhost 4444} on many systems) or GDB.
+@xref{GDB and OpenOCD}.
+
+@section Project Directory
+
+There are many ways you can configure OpenOCD and start it up.
+
+A simple way to organize them all involves keeping a
+single directory for your work with a given board.
+When you start OpenOCD from that directory,
+it searches there first for configuration files, scripts,
+and for code you upload to the target board.
+It is also the natural place to write files,
+such as log files and data you download from the board.
+
+@section Configuration Basics
+
+There are two basic ways of configuring OpenOCD, and
+a variety of ways you can mix them.
+Think of the difference as just being how you start the server:
+
+@itemize
+@item Many @option{-f file} or @option{-c command} options on the command line
+@item No options, but a @dfn{user config file}
+in the current directory named @file{openocd.cfg}
+@end itemize
+
+Here is an example @file{openocd.cfg} file for a setup
+using a Signalyzer FT2232-based JTAG adapter to talk to
+a board with an Atmel AT91SAM7X256 microcontroller:
+
+@example
+source [find interface/signalyzer.cfg]
+
+# GDB can also flash my flash!
+gdb_memory_map enable
+gdb_flash_program enable
+
+source [find target/sam7x256.cfg]
+@end example
+
+Here is the command line equivalent of that configuration:
+
+@example
+openocd -f interface/signalyzer.cfg \
+ -c "gdb_memory_map enable" \
+ -c "gdb_flash_program enable" \
+ -f target/sam7x256.cfg
+@end example
+
+You could wrap such long command lines in shell scripts,
+each supporting a different development task.
+One might re-flash the board with a specific firmware version.
+Another might set up a particular debugging or run-time environment.
+
+@quotation Important
+At this writing (October 2009) the command line method has
+problems with how it treats variables.
+For example, after @option{-c "set VAR value"}, or doing the
+same in a script, the variable @var{VAR} will have no value
+that can be tested in a later script.
+@end quotation
+
+Here we will focus on the simpler solution: one user config
+file, including basic configuration plus any TCL procedures
+to simplify your work.
+
+@section User Config Files
+@cindex config file, user
+@cindex user config file
+@cindex config file, overview
+
+A user configuration file ties together all the parts of a project
+in one place.
+One of the following will match your situation best:
+
+@itemize
+@item Ideally almost everything comes from configuration files
+provided by someone else.
+For example, OpenOCD distributes a @file{scripts} directory
+(probably in @file{/usr/share/openocd/scripts} on Linux).
+Board and tool vendors can provide these too, as can individual
+user sites; the @option{-s} command line option lets you say
+where to find these files. (@xref{Running}.)
+The AT91SAM7X256 example above works this way.
+
+Three main types of non-user configuration file each have their
+own subdirectory in the @file{scripts} directory:
+
+@enumerate
+@item @b{interface} -- one for each kind of JTAG adapter/dongle
+@item @b{board} -- one for each different board
+@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
+@end enumerate
+
+Best case: include just two files, and they handle everything else.
+The first is an interface config file.
+The second is board-specific, and it sets up the JTAG TAPs and
+their GDB targets (by deferring to some @file{target.cfg} file),
+declares all flash memory, and leaves you nothing to do except
+meet your deadline:
+
+@example
+source [find interface/olimex-jtag-tiny.cfg]
+source [find board/csb337.cfg]
+@end example
+
+Boards with a single microcontroller often won't need more
+than the target config file, as in the AT91SAM7X256 example.
+That's because there is no external memory (flash, DDR RAM), and
+the board differences are encapsulated by application code.
+
+@item You can often reuse some standard config files but
+need to write a few new ones, probably a @file{board.cfg} file.
+You will be using commands described later in this User's Guide,
+and working with the guidelines in the next chapter.
+
+For example, there may be configuration files for your JTAG adapter
+and target chip, but you need a new board-specific config file
+giving access to your particular flash chips.
+Or you might need to write another target chip configuration file
+for a new chip built around the Cortex M3 core.
+
+@quotation Note
+When you write new configuration files, please submit
+them for inclusion in the next OpenOCD release.
+For example, a @file{board/newboard.cfg} file will help the
+next users of that board, and a @file{target/newcpu.cfg}
+will help support users of any board using that chip.
+@end quotation
+