+@item @b{GW16402}
+@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
+
+@item @b{Wiggler2}
+@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
+
+@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, link:
+@url{http://www.st.com/stonline/products/literature/um/7889.pdf}
+Title: 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 Running
+@chapter Running
+@cindex running OpenOCD
+@cindex --configfile
+@cindex --debug_level
+@cindex --logfile
+@cindex --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 ``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
+
+Once started, OpenOCD runs as a daemon, waiting for connections from
+clients (Telnet, GDB, Other).
+
+If you are having problems, you can enable internal debug messages via
+the ``-d'' option.
+
+Also it is possible to interleave 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 @option{debug_level
+<n>} @xref{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 Simple Configuration Files
+@chapter Simple Configuration Files
+@cindex configuration
+
+@section Outline
+There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
+
+@enumerate
+@item A small openocd.cfg file which ``sources'' other configuration files
+@item A monolithic openocd.cfg file
+@item Many -f filename options on the command line
+@item Your Mixed Solution
+@end enumerate
+
+@section Small configuration file method
+
+This is the preferred method. It is simple and works well for many
+people. The developers of OpenOCD would encourage you to use this
+method. If you create a new configuration please email new
+configurations to the development list.
+
+Here is an example of an openocd.cfg file for an ATMEL at91sam7x256
+
+@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
+
+There are many example configuration scripts you can work with. You
+should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
+should find:
+
+@enumerate
+@item @b{board} - eval board level configurations
+@item @b{interface} - specific dongle configurations
+@item @b{target} - the target chips
+@item @b{tcl} - helper scripts
+@item @b{xscale} - things specific to the xscale.
+@end enumerate
+
+Look first in the ``boards'' area, then the ``targets'' area. Often a board
+configuration is a good example to work from.
+
+@section Many -f filename options
+Some believe this is a wonderful solution, others find it painful.
+
+You can use a series of ``-f filename'' options on the command line,
+OpenOCD will read each filename in sequence, for example:
+
+@example
+ openocd -f file1.cfg -f file2.cfg -f file2.cfg
+@end example
+
+You can also intermix various commands with the ``-c'' command line
+option.
+
+@section Monolithic file
+The ``Monolithic File'' dispenses with all ``source'' statements and
+puts everything in one self contained (monolithic) file. This is not
+encouraged.
+
+Please try to ``source'' various files or use the multiple -f
+technique.
+
+@section Advice for you
+Often, one uses a ``mixed approach''. Where possible, please try to
+``source'' common things, and if needed cut/paste parts of the
+standard distribution configuration files as needed.
+
+@b{REMEMBER:} The ``important parts'' of your configuration file are:
+
+@enumerate
+@item @b{Interface} - Defines the dongle
+@item @b{Taps} - Defines the JTAG Taps
+@item @b{GDB Targets} - What GDB talks to
+@item @b{Flash Programing} - Very Helpful
+@end enumerate
+
+Some key things you should look at and understand are:
+
+@enumerate
+@item The reset configuration of your debug environment as a whole
+@item Is there a ``work area'' that OpenOCD can use?
+@* For ARM - work areas mean up to 10x faster downloads.
+@item For MMU/MPU based ARM chips (i.e.: ARM9 and later) will that work area still be available?
+@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
+@end enumerate
+
+
+
+@node Config File Guidelines
+@chapter Config File Guidelines
+
+This section/chapter is aimed at developers and integrators of
+OpenOCD. These are guidelines for creating new boards and new target
+configurations as of 28/Nov/2008.
+
+However, you, the user of OpenOCD, should be somewhat familiar with
+this section as it should help explain some of the internals of what
+you might be looking at.
+
+The user should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
+
+@itemize @bullet
+@item @b{interface}
+@*Think JTAG Dongle. Files that configure the JTAG dongle go here.
+@item @b{board}
+@* Think Circuit Board, PWA, PCB, they go by many names. Board files
+contain initialization items that are specific to a board - for
+example: The SDRAM initialization sequence for the board, or the type
+of external flash and what address it is found at. Any initialization
+sequence to enable that external flash or SDRAM should be found in the
+board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
+a CPU and an FPGA or CPLD.
+@item @b{target}
+@* Think chip. The ``target'' directory represents a JTAG tap (or
+chip) OpenOCD should control, not a board. Two common types of targets
+are ARM chips and FPGA or CPLD chips.
+@end itemize
+
+@b{If needed...} The user in their ``openocd.cfg'' file or the board
+file might override a specific feature in any of the above files by
+setting a variable or two before sourcing the target file. Or adding
+various commands specific to their situation.
+
+@section Interface Config Files
+
+The user should be able to source one of these files via a command like this:
+
+@example
+ source [find interface/FOOBAR.cfg]
+Or:
+ openocd -f interface/FOOBAR.cfg
+@end example
+
+A preconfigured interface file should exist for every interface in use
+today, that said, perhaps some interfaces have only been used by the
+sole developer who created it.
+
+@b{FIXME/NOTE:} We need to add support for a variable like Tcl variable
+tcl_platform(platform), it should be called jim_platform (because it
+is jim, not real tcl) and it should contain 1 of 3 words: ``linux'',
+``cygwin'' or ``mingw''
+
+Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
+
+@section Board Config Files
+
+@b{Note: BOARD directory NEW as of 28/nov/2008}
+
+The user should be able to source one of these files via a command like this:
+
+@example
+ source [find board/FOOBAR.cfg]
+Or:
+ openocd -f board/FOOBAR.cfg
+@end example
+
+
+The board file should contain one or more @t{source [find
+target/FOO.cfg]} statements along with any board specific things.
+
+In summary the board files should contain (if present)
+
+@enumerate
+@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
+@item SDRAM configuration (size, speed, etc.
+@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
+@item Multiple TARGET source statements
+@item All things that are not ``inside a chip''
+@item Things inside a chip go in a 'target' file
+@end enumerate
+
+@section Target Config Files
+
+The user should be able to source one of these files via a command like this:
+
+@example
+ source [find target/FOOBAR.cfg]
+Or:
+ openocd -f target/FOOBAR.cfg
+@end example
+
+In summary the target files should contain
+
+@enumerate
+@item Set defaults
+@item Create taps
+@item Reset configuration
+@item Work areas
+@item CPU/Chip/CPU-Core specific features
+@item On-Chip flash
+@end enumerate
+
+@subsection Important variable names
+
+By default, the end user should never need to set these
+variables. However, if the user needs to override a setting they only
+need to set the variable in a simple way.
+
+@itemize @bullet
+@item @b{CHIPNAME}
+@* This gives a name to the overall chip, and is used as part of the
+tap identifier dotted name.
+@item @b{ENDIAN}
+@* By default little - unless the chip or board is not normally used that way.
+@item @b{CPUTAPID}
+@* When OpenOCD examines the JTAG chain, it will attempt to identify
+every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
+to verify the tap id number verses configuration file and may issue an
+error or warning like this. The hope is that this will help to pinpoint
+problems in OpenOCD configurations.
+
+@example
+Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
+Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
+Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
+Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
+@end example
+
+@item @b{_TARGETNAME}
+@* By convention, this variable is created by the target configuration
+script. The board configuration file may make use of this variable to
+configure things like a ``reset init'' script, or other things
+specific to that board and that target.
+
+If the chip has 2 targets, use the names @b{_TARGETNAME0},
+@b{_TARGETNAME1}, ... etc.
+
+@b{Remember:} The ``board file'' may include multiple targets.
+
+At no time should the name ``target0'' (the default target name if
+none was specified) be used. The name ``target0'' is a hard coded name
+- the next target on the board will be some other number.
+In the same way, avoid using target numbers even when they are
+permitted; use the right target name(s) for your board.
+
+The user (or board file) should reasonably be able to:
+
+@example
+ source [find target/FOO.cfg]
+ $_TARGETNAME configure ... FOO specific parameters
+
+ source [find target/BAR.cfg]
+ $_TARGETNAME configure ... BAR specific parameters
+@end example
+
+@end itemize
+
+@subsection Tcl Variables Guide Line
+The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
+
+Thus the rule we follow in OpenOCD is this: Variables that begin with
+a leading underscore are temporary in nature, and can be modified and
+used at will within a ?TARGET? configuration file.
+
+@b{EXAMPLE:} The user should be able to do this:
+
+@example
+ # Board has 3 chips,
+ # PXA270 #1 network side, big endian
+ # PXA270 #2 video side, little endian
+ # Xilinx Glue logic
+ set CHIPNAME network
+ set ENDIAN big
+ source [find target/pxa270.cfg]
+ # variable: _TARGETNAME = network.cpu
+ # other commands can refer to the "network.cpu" tap.
+ $_TARGETNAME configure .... params for this CPU..
+
+ set ENDIAN little
+ set CHIPNAME video
+ source [find target/pxa270.cfg]
+ # variable: _TARGETNAME = video.cpu
+ # other commands can refer to the "video.cpu" tap.
+ $_TARGETNAME configure .... params for this CPU..
+
+ unset ENDIAN
+ set CHIPNAME xilinx
+ source [find target/spartan3.cfg]
+
+ # Since $_TARGETNAME is temporal..
+ # these names still work!
+ network.cpu configure ... params
+ video.cpu configure ... params
+
+@end example
+
+@subsection Default Value Boiler Plate Code
+
+All target configuration files should start with this (or a modified form)
+
+@example
+# SIMPLE example
+if @{ [info exists CHIPNAME] @} @{
+ set _CHIPNAME $CHIPNAME
+@} else @{
+ set _CHIPNAME sam7x256
+@}
+
+if @{ [info exists ENDIAN] @} @{
+ set _ENDIAN $ENDIAN
+@} else @{
+ set _ENDIAN little
+@}
+
+if @{ [info exists CPUTAPID ] @} @{
+ set _CPUTAPID $CPUTAPID
+@} else @{
+ set _CPUTAPID 0x3f0f0f0f
+@}
+
+@end example
+
+@subsection Creating Taps
+After the ``defaults'' are choosen [see above] the taps are created.
+
+@b{SIMPLE example:} such as an Atmel AT91SAM7X256
+
+@example
+# for an ARM7TDMI.
+set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
+@end example
+
+@b{COMPLEX example:}
+
+This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
+
+@enumerate
+@item @b{Unform tap names} - See: Tap Naming Convention
+@item @b{_TARGETNAME} is created at the end where used.
+@end enumerate
+
+@example
+if @{ [info exists FLASHTAPID ] @} @{
+ set _FLASHTAPID $FLASHTAPID
+@} else @{
+ set _FLASHTAPID 0x25966041
+@}
+jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 -expected-id $_FLASHTAPID
+
+if @{ [info exists CPUTAPID ] @} @{
+ set _CPUTAPID $CPUTAPID
+@} else @{
+ set _CPUTAPID 0x25966041
+@}
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe -expected-id $_CPUTAPID
+
+
+if @{ [info exists BSTAPID ] @} @{
+ set _BSTAPID $BSTAPID
+@} else @{
+ set _BSTAPID 0x1457f041
+@}
+jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 -expected-id $_BSTAPID
+
+set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
+@end example
+
+@b{Tap Naming Convention}
+
+See the command ``jtag newtap'' for detail, but in brief the names you should use are:
+
+@itemize @bullet
+@item @b{tap}
+@item @b{cpu}
+@item @b{flash}
+@item @b{bs}
+@item @b{etb}
+@item @b{jrc}
+@item @b{unknownN} - it happens :-(
+@end itemize
+
+@subsection Reset Configuration
+
+Some chips have specific ways the TRST and SRST signals are
+managed. If these are @b{CHIP SPECIFIC} they go here, if they are
+@b{BOARD SPECIFIC} they go in the board file.
+
+@subsection Work Areas
+
+Work areas are small RAM areas used by OpenOCD to speed up downloads,
+and to download small snippets of code to program flash chips.
+
+If the chip includes a form of ``on-chip-ram'' - and many do - define
+a reasonable work area and use the ``backup'' option.
+
+@b{PROBLEMS:} On more complex chips, this ``work area'' may become
+inaccessible if/when the application code enables or disables the MMU.
+
+@subsection ARM Core Specific Hacks
+
+If the chip has a DCC, enable it. If the chip is an ARM9 with some
+special high speed download features - enable it.
+
+If the chip has an ARM ``vector catch'' feature - by default enable
+it for Undefined Instructions, Data Abort, and Prefetch Abort, if the
+user is really writing a handler for those situations - they can
+easily disable it. Experiance has shown the ``vector catch'' is
+helpful - for common programing errors.
+
+If present, the MMU, the MPU and the CACHE should be disabled.
+
+Some ARM cores are equipped with trace support, which permits
+examination of the instruction and data bus activity. Trace
+activity is controlled through an ``Embedded Trace Module'' (ETM)
+on one of the core's scan chains. The ETM emits voluminous data
+through a ``trace port''. The trace port is accessed in one
+of two ways. When its signals are pinned out from the chip,
+boards may provide a special high speed debugging connector;
+software support for this is not configured by default, use
+the ``--enable-oocd_trace'' option. Alternatively, trace data
+may be stored an on-chip SRAM which is packaged as an ``Embedded
+Trace Buffer'' (ETB). An ETB has its own TAP, usually right after
+its associated ARM core. OpenOCD supports the ETM, and your
+target configuration should set it up with the relevant trace
+port: ``etb'' for chips which use that, else the board-specific
+option will be either ``oocd_trace'' or ``dummy''.
+
+@example
+etm config $_TARGETNAME 16 normal full etb
+etb config $_TARGETNAME $_CHIPNAME.etb
+@end example
+
+@subsection Internal Flash Configuration
+
+This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
+
+@b{Never ever} in the ``target configuration file'' define any type of
+flash that is external to the chip. (For example a BOOT flash on
+Chip Select 0.) Such flash information goes in a board file - not
+the TARGET (chip) file.
+
+Examples:
+@itemize @bullet
+@item at91sam7x256 - has 256K flash YES enable it.
+@item str912 - has flash internal YES enable it.
+@item imx27 - uses boot flash on CS0 - it goes in the board file.
+@item pxa270 - again - CS0 flash - it goes in the board file.
+@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. You can
+learn more about JIM here: @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
+impliments the basic Tcl command set along. 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 (28/nov/2008) 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.
+
+@item @b{Historical Note}
+@* JIM-Tcl was introduced to OpenOCD in spring 2008.
+
+@item @b{Need a crash course in Tcl?}
+@* See: @xref{Tcl Crash Course}.
+@end itemize
+
+
+@node Daemon Configuration
+@chapter Daemon Configuration
+@cindex initialization
+The commands here are commonly found in the openocd.cfg file and are
+used to specify what TCP/IP ports are used, and how GDB should be
+supported.
+
+@section Configuration Stage
+@cindex configuration stage
+@cindex configuration command
+
+When the OpenOCD server process starts up, it enters a
+@emph{configuration stage} which is the only time that
+certain commands, @emph{configuration commands}, may be issued.
+Those configuration commands include declaration of TAPs
+and other basic setup.
+The server must leave the configuration stage before it
+may access or activate TAPs.
+After it leaves this stage, configuration commands may no
+longer be issued.
+
+@deffn {Config Command} init
+This command terminates the configuration stage and
+enters the normal command mode. This can be useful to add commands to
+the startup scripts and commands such as resetting the target,
+programming flash, etc. To reset the CPU upon startup, add "init" and
+"reset" at the end of the config script or at the end of the OpenOCD
+command line using the @option{-c} command line switch.
+
+If this command does not appear in any startup/configuration file
+OpenOCD executes the command for you after processing all
+configuration files and/or command line options.
+
+@b{NOTE:} This command normally occurs at or near the end of your
+openocd.cfg file to force OpenOCD to ``initialize'' and make the
+targets ready. For example: If your openocd.cfg file needs to
+read/write memory on your target, @command{init} must occur before
+the memory read/write commands. This includes @command{nand probe}.
+@end deffn
+
+@section TCP/IP Ports
+@cindex TCP port
+@cindex server
+@cindex port
+The OpenOCD server accepts remote commands in several syntaxes.
+Each syntax uses a different TCP/IP port, which you may specify
+only during configuration (before those ports are opened).
+
+@deffn {Command} gdb_port (number)
+@cindex GDB server
+Specify or query the first port used for incoming GDB connections.
+The GDB port for the
+first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+When not specified during the configuration stage,
+the port @var{number} defaults to 3333.
+@end deffn
+
+@deffn {Command} tcl_port (number)
+Specify or query the port used for a simplified RPC
+connection that can be used by clients to issue TCL commands and get the
+output from the Tcl engine.
+Intended as a machine interface.
+When not specified during the configuration stage,
+the port @var{number} defaults to 6666.
+@end deffn
+
+@deffn {Command} telnet_port (number)
+Specify or query the
+port on which to listen for incoming telnet connections.
+This port is intended for interaction with one human through TCL commands.
+When not specified during the configuration stage,
+the port @var{number} defaults to 4444.
+@end deffn
+
+@section GDB Configuration
+@anchor{GDB Configuration}
+@cindex GDB
+@cindex GDB configuration
+You can reconfigure some GDB behaviors if needed.
+The ones listed here are static and global.
+@xref{Target Create}, about declaring individual targets.
+@xref{Target Events}, about configuring target-specific event handling.
+
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
+@anchor{gdb_breakpoint_override}
+Force breakpoint type for gdb @command{break} commands.
+The raison d'etre for this option is to support GDB GUI's which don't
+distinguish hard versus soft breakpoints, if the default OpenOCD and
+GDB behaviour is not sufficient. GDB normally uses hardware
+breakpoints if the memory map has been set up for flash regions.
+
+This option replaces older arm7_9 target commands that addressed
+the same issue.
+@end deffn
+
+@deffn {Config command} gdb_detach <resume|reset|halt|nothing>
+Configures what OpenOCD will do when GDB detaches from the daemon.
+Default behaviour is @var{resume}.
+@end deffn
+
+@deffn {Config command} gdb_flash_program <enable|disable>
+@anchor{gdb_flash_program}
+Set to @var{enable} to cause OpenOCD to program the flash memory when a
+vFlash packet is received.
+The default behaviour is @var{enable}.
+@end deffn
+
+@deffn {Config command} gdb_memory_map <enable|disable>
+Set to @var{enable} to cause OpenOCD to send the memory configuration to GDB when
+requested. GDB will then know when to set hardware breakpoints, and program flash
+using the GDB load command. @command{gdb_flash_program enable} must also be enabled
+for flash programming to work.
+Default behaviour is @var{enable}.
+@xref{gdb_flash_program}.
+@end deffn
+
+@deffn {Config command} gdb_report_data_abort <enable|disable>
+Specifies whether data aborts cause an error to be reported
+by GDB memory read packets.
+The default behaviour is @var{disable};
+use @var{enable} see these errors reported.
+@end deffn
+
+@node Interface - Dongle Configuration
+@chapter Interface - Dongle Configuration
+Interface commands are normally found in an interface configuration
+file which is sourced by your openocd.cfg file. These commands tell
+OpenOCD what type of JTAG dongle you have and how to talk to it.
+@section Simple Complete Interface Examples
+@b{A Turtelizer FT2232 Based JTAG Dongle}
+@verbatim
+#interface
+interface ft2232
+ft2232_device_desc "Turtelizer JTAG/RS232 Adapter A"
+ft2232_layout turtelizer2
+ft2232_vid_pid 0x0403 0xbdc8
+@end verbatim
+@b{A SEGGER Jlink}
+@verbatim
+# jlink interface
+interface jlink
+@end verbatim
+@b{A Raisonance RLink}
+@verbatim
+# rlink interface
+interface rlink
+@end verbatim
+@b{Parallel Port}
+@verbatim
+interface parport
+parport_port 0xc8b8
+parport_cable wiggler
+jtag_speed 0
+@end verbatim
+@b{ARM-JTAG-EW}
+@verbatim
+interface arm-jtag-ew
+@end verbatim
+@section Interface Command
+
+The interface command tells OpenOCD what type of JTAG dongle you are
+using. Depending on the type of dongle, you may need to have one or
+more additional commands.
+
+@itemize @bullet
+
+@item @b{interface} <@var{name}>
+@cindex interface
+@*Use the interface driver <@var{name}> to connect to the
+target. Currently supported interfaces are
+
+@itemize @minus
+
+@item @b{parport}
+@* PC parallel port bit-banging (Wigglers, PLD download cable, ...)
+
+@item @b{amt_jtagaccel}
+@* Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
+mode parallel port
+
+@item @b{ft2232}
+@* FTDI FT2232 (USB) based devices using either the open-source libftdi or the binary only
+FTD2XX driver. The FTD2XX is superior in performance, but not available on every
+platform. The libftdi uses libusb, and should be portable to all systems that provide
+libusb.
+
+@item @b{ep93xx}
+@*Cirrus Logic EP93xx based single-board computer bit-banging (in development)
+
+@item @b{presto}
+@* ASIX PRESTO USB JTAG programmer.
+
+@item @b{usbprog}
+@* usbprog is a freely programmable USB adapter.
+
+@item @b{gw16012}
+@* Gateworks GW16012 JTAG programmer.
+
+@item @b{jlink}
+@* Segger jlink USB adapter
+
+@item @b{rlink}
+@* Raisonance RLink USB adapter
+
+@item @b{vsllink}
+@* vsllink is part of Versaloon which is a versatile USB programmer.
+
+@item @b{arm-jtag-ew}
+@* Olimex ARM-JTAG-EW USB adapter
+@comment - End parameters
+@end itemize
+@comment - End Interface
+@end itemize
+@subsection parport options
+
+@itemize @bullet
+@item @b{parport_port} <@var{number}>
+@cindex parport_port
+@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of
+the @file{/dev/parport} device
+
+When using PPDEV to access the parallel port, use the number of the parallel port:
+@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
+you may encounter a problem.
+@item @b{parport_cable} <@var{name}>
+@cindex parport_cable
+@*The layout of the parallel port cable used to connect to the target.
+Currently supported cables are
+@itemize @minus
+@item @b{wiggler}
+@cindex wiggler
+The original Wiggler layout, also supported by several clones, such
+as the Olimex ARM-JTAG
+@item @b{wiggler2}
+@cindex wiggler2
+Same as original wiggler except an led is fitted on D5.
+@item @b{wiggler_ntrst_inverted}
+@cindex wiggler_ntrst_inverted
+Same as original wiggler except TRST is inverted.
+@item @b{old_amt_wiggler}
+@cindex old_amt_wiggler
+The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
+version available from the website uses the original Wiggler layout ('@var{wiggler}')
+@item @b{chameleon}
+@cindex chameleon
+The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to
+program the Chameleon itself, not a connected target.
+@item @b{dlc5}
+@cindex dlc5
+The Xilinx Parallel cable III.
+@item @b{triton}
+@cindex triton
+The parallel port adapter found on the 'Karo Triton 1 Development Board'.
+This is also the layout used by the HollyGates design
+(see @uref{http://www.lartmaker.nl/projects/jtag/}).
+@item @b{flashlink}
+@cindex flashlink
+The ST Parallel cable.
+@item @b{arm-jtag}
+@cindex arm-jtag
+Same as original wiggler except SRST and TRST connections reversed and
+TRST is also inverted.
+@item @b{altium}
+@cindex altium
+Altium Universal JTAG cable.
+@end itemize
+@item @b{parport_write_on_exit} <@var{on}|@var{off}>
+@cindex parport_write_on_exit
+@*This will configure the parallel driver to write a known value to the parallel
+interface on exiting OpenOCD
+@end itemize
+
+@subsection amt_jtagaccel options
+@itemize @bullet
+@item @b{parport_port} <@var{number}>
+@cindex parport_port
+@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
+@file{/dev/parport} device
+@end itemize
+@subsection ft2232 options
+
+@itemize @bullet
+@item @b{ft2232_device_desc} <@var{description}>
+@cindex ft2232_device_desc
+@*The USB device description of the FTDI FT2232 device. If not
+specified, the FTDI default value is used. This setting is only valid
+if compiled with FTD2XX support.
+
+@b{TODO:} Confirm the following: On Windows the name needs to end with
+a ``space A''? Or not? It has to do with the FTD2xx driver. When must
+this be added and when must it not be added? Why can't the code in the
+interface or in OpenOCD automatically add this if needed? -- Duane.
+
+@item @b{ft2232_serial} <@var{serial-number}>
+@cindex ft2232_serial
+@*The serial number of the FTDI FT2232 device. If not specified, the FTDI default
+values are used.
+@item @b{ft2232_layout} <@var{name}>
+@cindex ft2232_layout
+@*The layout of the FT2232 GPIO signals used to control output-enables and reset
+signals. Valid layouts are
+@itemize @minus
+@item @b{usbjtag}
+"USBJTAG-1" layout described in the original OpenOCD diploma thesis
+@item @b{jtagkey}
+Amontec JTAGkey and JTAGkey-Tiny
+@item @b{signalyzer}
+Signalyzer
+@item @b{olimex-jtag}
+Olimex ARM-USB-OCD
+@item @b{m5960}
+American Microsystems M5960
+@item @b{evb_lm3s811}
+Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
+SRST signals on external connector
+@item @b{comstick}
+Hitex STR9 comstick
+@item @b{stm32stick}
+Hitex STM32 Performance Stick
+@item @b{flyswatter}
+Tin Can Tools Flyswatter
+@item @b{turtelizer2}
+egnite Software turtelizer2
+@item @b{oocdlink}
+OOCDLink
+@item @b{axm0432_jtag}
+Axiom AXM-0432
+@item @b{cortino}
+Hitex Cortino JTAG interface
+@end itemize
+
+@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
+@*The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
+default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, e.g.
+@example
+ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+@end example
+@item @b{ft2232_latency} <@var{ms}>
+@*On some systems using FT2232 based JTAG interfaces the FT_Read function call in
+ft2232_read() fails to return the expected number of bytes. This can be caused by
+USB communication delays and has proved hard to reproduce and debug. Setting the
+FT2232 latency timer to a larger value increases delays for short USB packets but it
+also reduces the risk of timeouts before receiving the expected number of bytes.
+The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
+@end itemize
+
+@subsection ep93xx options
+@cindex ep93xx options
+Currently, there are no options available for the ep93xx interface.
+
+@section JTAG Speed
+@anchor{JTAG Speed}
+JTAG clock setup is part of system setup.
+It @emph{does not belong with interface setup} since any interface
+only knows a few of the constraints for the JTAG clock speed.
+Sometimes the JTAG speed is
+changed during the target initialization process: (1) slow at
+reset, (2) program the CPU clocks, (3) run fast.
+Both the "slow" and "fast" clock rates are functions of the
+oscillators used, the chip, the board design, and sometimes
+power management software that may be active.
+
+The speed used during reset can be adjusted using pre_reset
+and post_reset event handlers.
+@xref{Target Events}.
+
+If your system supports adaptive clocking (RTCK), configuring
+JTAG to use that is probably the most robust approach.
+However, it introduces delays to synchronize clocks; so it
+may not be the fastest solution.
+
+@b{NOTE:} Script writers should consider using @command{jtag_rclk}
+instead of @command{jtag_khz}.
+
+@deffn {Command} jtag_khz max_speed_kHz
+A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+JTAG interfaces usually support a limited number of
+speeds. The speed actually used won't be faster
+than the speed specified.
+
+As a rule of thumb, if you specify a clock rate make
+sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
+This is especially true for synthesized cores (ARMxxx-S).
+
+Speed 0 (khz) selects RTCK method.
+@xref{FAQ RTCK}.
+If your system uses RTCK, you won't need to change the
+JTAG clocking after setup.
+Not all interfaces, boards, or targets support ``rtck''.
+If the interface device can not
+support it, an error is returned when you try to use RTCK.
+@end deffn
+
+@defun jtag_rclk fallback_speed_kHz
+@cindex RTCK
+This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK.
+If that fails (maybe the interface, board, or target doesn't
+support it), falls back to the specified frequency.
+@example
+# Fall back to 3mhz if RTCK is not supported
+jtag_rclk 3000
+@end example
+@end defun
+
+@node Reset Configuration
+@chapter Reset Configuration
+@cindex Reset Configuration
+
+Every system configuration may require a different reset
+configuration. This can also be quite confusing.
+Please see the various board files for examples.
+
+@b{Note} to maintainers and integrators:
+Reset configuration touches several things at once.
+Normally the board configuration file
+should define it and assume that the JTAG adapter supports
+everything that's wired up to the board's JTAG connector.
+However, the target configuration file could also make note
+of something the silicon vendor has done inside the chip,
+which will be true for most (or all) boards using that chip.
+And when the JTAG adapter doesn't support everything, the
+system configuration file will need to override parts of
+the reset configuration provided by other files.
+
+@section Types of Reset
+
+There are many kinds of reset possible through JTAG, but
+they may not all work with a given board and adapter.
+That's part of why reset configuration can be error prone.
+
+@itemize @bullet
+@item
+@emph{System Reset} ... the @emph{SRST} hardware signal
+resets all chips connected to the JTAG adapter, such as processors,
+power management chips, and I/O controllers. Normally resets triggered
+with this signal behave exactly like pressing a RESET button.
+@item
+@emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
+just the TAP controllers connected to the JTAG adapter.
+Such resets should not be visible to the rest of the system; resetting a
+device's the TAP controller just puts that controller into a known state.
+@item
+@emph{Emulation Reset} ... many devices can be reset through JTAG
+commands. These resets are often distinguishable from system
+resets, either explicitly (a "reset reason" register says so)
+or implicitly (not all parts of the chip get reset).
+@item
+@emph{Other Resets} ... system-on-chip devices often support
+several other types of reset.
+You may need to arrange that a watchdog timer stops
+while debugging, preventing a watchdog reset.
+There may be individual module resets.
+@end itemize
+
+In the best case, OpenOCD can hold SRST, then reset
+the TAPs via TRST and send commands through JTAG to halt the
+CPU at the reset vector before the 1st instruction is executed.
+Then when it finally releases the SRST signal, the system is
+halted under debugger control before any code has executed.
+This is the behavior required to support the @command{reset halt}
+and @command{reset init} commands; after @command{reset init} a
+board-specific script might do things like setting up DRAM.
+(@xref{Reset Command}.)
+
+@section SRST and TRST Signal Issues
+
+Because SRST and TRST are hardware signals, they can have a
+variety of system-specific constraints. Some of the most
+common issues are:
+
+@itemize @bullet
+
+@item @emph{Signal not available} ... Some boards don't wire
+SRST or TRST to the JTAG connector. Some JTAG adapters don't
+support such signals even if they are wired up.
+Use the @command{reset_config} @var{signals} options to say
+when one of those signals is not connected.
+When SRST is not available, your code might not be able to rely
+on controllers having been fully reset during code startup.
+
+@item @emph{Signals shorted} ... Sometimes a chip, board, or
+adapter will connect SRST to TRST, instead of keeping them separate.
+Use the @command{reset_config} @var{combination} options to say
+when those signals aren't properly independent.
+
+@item @emph{Timing} ... Reset circuitry like a resistor/capacitor
+delay circuit, reset supervisor, or on-chip features can extend
+the effect of a JTAG adapter's reset for some time after the adapter
+stops issuing the reset. For example, there may be chip or board
+requirements that all reset pulses last for at least a
+certain amount of time; and reset buttons commonly have
+hardware debouncing.
+Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
+commands to say when extra delays are needed.
+
+@item @emph{Drive type} ... Reset lines often have a pullup
+resistor, letting the JTAG interface treat them as open-drain
+signals. But that's not a requirement, so the adapter may need
+to use push/pull output drivers.
+Also, with weak pullups it may be advisable to drive
+signals to both levels (push/pull) to minimize rise times.
+Use the @command{reset_config} @var{trst_type} and
+@var{srst_type} parameters to say how to drive reset signals.
+@end itemize
+
+There can also be other issues.
+Some devices don't fully conform to the JTAG specifications.
+Others have chip-specific extensions like extra steps needed
+during TAP reset, or a requirement to use the normally-optional TRST
+signal.
+Trivial system-specific differences are common, such as
+SRST and TRST using slightly different names.
+
+@section Commands for Handling Resets
+
+@deffn {Command} jtag_nsrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nSRST (active-low system reset) before starting new JTAG operations.
+When a board has a reset button connected to SRST line it will
+probably have hardware debouncing, implying you should use this.
+@end deffn
+
+@deffn {Command} jtag_ntrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
+@end deffn
+
+@deffn {Command} reset_config signals [combination [trst_type [srst_type]]]
+This command tells OpenOCD the reset configuration
+of your combination of JTAG interface, board, and target.
+If the JTAG interface provides SRST, but the board doesn't connect
+that signal properly, then OpenOCD can't use it. @var{signals} can
+be @option{none}, @option{trst_only}, @option{srst_only} or
+@option{trst_and_srst}.
+
+The @var{combination} is an optional value specifying broken reset
+signal implementations. @option{srst_pulls_trst} states that the
+test logic is reset together with the reset of the system (e.g. Philips
+LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
+the system is reset together with the test logic (only hypothetical, I
+haven't seen hardware with such a bug, and can be worked around).
+@option{combined} implies both @option{srst_pulls_trst} and
+@option{trst_pulls_srst}. The default behaviour if no option given is
+@option{separate}.
+
+The optional @var{trst_type} and @var{srst_type} parameters allow the
+driver type of the reset lines to be specified. Possible values are
+@option{trst_push_pull} (default) and @option{trst_open_drain} for the
+test reset signal, and @option{srst_open_drain} (default) and
+@option{srst_push_pull} for the system reset. These values only affect
+JTAG interfaces with support for different drivers, like the Amontec
+JTAGkey and JTAGAccelerator.
+@end deffn
+
+
+@node Tap Creation
+@chapter Tap Creation
+@cindex tap creation
+@cindex tap configuration
+
+In order for OpenOCD to control a target, a JTAG tap must be
+defined/created.
+
+Commands to create taps are normally found in a configuration file and
+are not normally typed by a human.
+
+When a tap is created a @b{dotted.name} is created for the tap. Other
+commands use that dotted.name to manipulate or refer to the tap.
+
+Tap Uses:
+@itemize @bullet
+@item @b{Debug Target} A tap can be used by a GDB debug target
+@item @b{Flash Programing} Some chips program the flash directly via JTAG,
+instead of indirectly by making a CPU do it.
+@item @b{Boundry Scan} Some chips support boundary scan.
+@end itemize
+
+
+@section jtag newtap
+@b{@t{jtag newtap CHIPNAME TAPNAME configparams ....}}
+@cindex jtag_device
+@cindex jtag newtap
+@cindex tap
+@cindex tap order
+@cindex tap geometry
+
+@comment START options
+@itemize @bullet
+@item @b{CHIPNAME}
+@* is a symbolic name of the chip.
+@item @b{TAPNAME}
+@* is a symbol name of a tap present on the chip.
+@item @b{Required configparams}
+@* Every tap has 3 required configparams, and several ``optional
+parameters'', the required parameters are:
+@comment START REQUIRED
+@itemize @bullet
+@item @b{-irlen NUMBER} - the length in bits of the instruction register, mostly 4 or 5 bits.
+@item @b{-ircapture NUMBER} - the IDCODE capture command, usually 0x01.
+@item @b{-irmask NUMBER} - the corresponding mask for the IR register. For
+some devices, there are bits in the IR that aren't used. This lets you mask
+them off when doing comparisons. In general, this should just be all ones for
+the size of the IR.
+@comment END REQUIRED
+@end itemize
+An example of a FOOBAR Tap
+@example
+jtag newtap foobar tap -irlen 7 -ircapture 0x42 -irmask 0x55
+@end example
+Creates the tap ``foobar.tap'' with the instruction register (IR) is 7
+bits long, during Capture-IR 0x42 is loaded into the IR, and bits
+[6,4,2,0] are checked.
+
+@item @b{Optional configparams}
+@comment START Optional
+@itemize @bullet
+@item @b{-expected-id NUMBER}
+@* By default it is zero. If non-zero represents the
+expected tap ID used when the JTAG chain is examined. Repeat
+the option as many times as required if multiple id's can be
+expected. See below.
+@item @b{-disable}
+@item @b{-enable}
+@* By default not specified the tap is enabled. Some chips have a
+JTAG route controller (JRC) that is used to enable and/or disable
+specific JTAG taps. You can later enable or disable any JTAG tap via
+the command @b{jtag tapenable DOTTED.NAME} or @b{jtag tapdisable
+DOTTED.NAME}
+@comment END Optional
+@end itemize
+
+@comment END OPTIONS
+@end itemize
+@b{Notes:}
+@comment START NOTES
+@itemize @bullet
+@item @b{Technically}
+@* newtap is a sub command of the ``jtag'' command
+@item @b{Big Picture Background}
+@*GDB Talks to OpenOCD using the GDB protocol via
+TCP/IP. OpenOCD then uses the JTAG interface (the dongle) to
+control the JTAG chain on your board. Your board has one or more chips
+in a @i{daisy chain configuration}. Each chip may have one or more
+JTAG taps. GDB ends up talking via OpenOCD to one of the taps.
+@item @b{NAME Rules}
+@*Names follow ``C'' symbol name rules (start with alpha ...)
+@item @b{TAPNAME - Conventions}
+@itemize @bullet
+@item @b{tap} - should be used only FPGA or CPLD like devices with a single tap.
+@item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp}
+@item @b{flash} - if the chip has a flash tap, example: str912.flash
+@item @b{bs} - for boundary scan if this is a seperate tap.
+@item @b{etb} - for an embedded trace buffer (example: an ARM ETB11)
+@item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards)
+@item @b{unknownN} - where N is a number if you have no idea what the tap is for
+@item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap.
+@item @b{When in doubt} - use the chip maker's name in their data sheet.
+@end itemize
+@item @b{DOTTED.NAME}
+@* @b{CHIPNAME}.@b{TAPNAME} creates the tap name, aka: the
+@b{Dotted.Name} is the @b{CHIPNAME} and @b{TAPNAME} combined with a
+dot (period); for example: @b{xilinx.tap}, @b{str912.flash},
+@b{omap3530.jrc}, or @b{stm32.cpu} The @b{dotted.name} is used in
+numerous other places to refer to various taps.
+@item @b{ORDER}
+@* The order this command appears via the config files is
+important.
+@item @b{Multi Tap Example}
+@* This example is based on the ST Microsystems STR912. See the ST
+document titled: @b{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
+28/102, Figure 3: JTAG chaining inside the STR91xFA}.
+
+@url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}
+@*@b{checked: 28/nov/2008}
+
+The diagram shows that the TDO pin connects to the flash tap, flash TDI
+connects to the CPU debug tap, CPU TDI connects to the boundary scan
+tap which then connects to the TDI pin.
+
+@example
+ # The order is...
+ # create tap: 'str912.flash'
+ jtag newtap str912 flash ... params ...
+ # create tap: 'str912.cpu'
+ jtag newtap str912 cpu ... params ...
+ # create tap: 'str912.bs'
+ jtag newtap str912 bs ... params ...
+@end example
+
+@item @b{Note: Deprecated} - Index Numbers
+@* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this
+feature is still present, however its use is highly discouraged and
+should not be counted upon. Update all of your scripts to use
+TAP names rather than numbers.
+@item @b{Multiple chips}
+@* If your board has multiple chips, you should be
+able to @b{source} two configuration files, in the proper order, and
+have the taps created in the proper order.
+@comment END NOTES
+@end itemize
+@comment at command level
+@comment DOCUMENT old command
+@section jtag_device - REMOVED
+@example
+@b{jtag_device} <@var{IR length}> <@var{IR capture}> <@var{IR mask}> <@var{IDCODE instruction}>
+@end example
+@cindex jtag_device
+
+@* @b{Removed: 28/nov/2008} This command has been removed and replaced
+by the ``jtag newtap'' command. The documentation remains here so that
+one can easily convert the old syntax to the new syntax. About the old
+syntax: The old syntax is positional, i.e.: The 3rd parameter is the
+``irmask''. The new syntax requires named prefixes, and supports
+additional options, for example ``-expected-id 0x3f0f0f0f''. Please refer to the
+@b{jtag newtap} command for details.
+@example
+OLD: jtag_device 8 0x01 0xe3 0xfe
+NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3
+@end example
+
+@section Enable/Disable Taps
+@b{Note:} These commands are intended to be used as a machine/script
+interface. Humans might find the ``scan_chain'' command more helpful
+when querying the state of the JTAG taps.
+
+@b{By default, all taps are enabled}
+
+@itemize @bullet
+@item @b{jtag tapenable} @var{DOTTED.NAME}
+@item @b{jtag tapdisable} @var{DOTTED.NAME}
+@item @b{jtag tapisenabled} @var{DOTTED.NAME}
+@end itemize
+@cindex tap enable
+@cindex tap disable
+@cindex JRC
+@cindex route controller
+
+These commands are used when your target has a JTAG route controller
+that effectively adds or removes a tap from the JTAG chain in a
+non-standard way.
+
+The ``standard way'' to remove a tap would be to place the tap in
+bypass mode. But with the advent of modern chips, this is not always a
+good solution. Some taps operate slowly, others operate fast, and
+there are other JTAG clock synchronisation problems one must face. To
+solve that problem, the JTAG route controller was introduced. Rather
+than ``bypass'' the tap, the tap is completely removed from the
+circuit and skipped.
+
+
+From OpenOCD's point of view, a JTAG tap is in one of 3 states:
+
+@itemize @bullet
+@item @b{Enabled - Not In ByPass} and has a variable bit length
+@item @b{Enabled - In ByPass} and has a length of exactly 1 bit.
+@item @b{Disabled} and has a length of ZERO and is removed from the circuit.
+@end itemize
+
+The IEEE JTAG definition has no concept of a ``disabled'' tap.
+@b{Historical note:} this feature was added 28/nov/2008
+
+@b{jtag tapisenabled DOTTED.NAME}
+
+This command returns 1 if the named tap is currently enabled, 0 if not.
+This command exists so that scripts that manipulate a JRC (like the
+OMAP3530 has) can determine if OpenOCD thinks a tap is presently
+enabled or disabled.
+
+@page
+@node Target Configuration
+@chapter Target Configuration
+@cindex GDB target
+
+This chapter discusses how to create a GDB debug target. Before
+creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
+
+@section targets [NAME]
+@b{Note:} This command name is PLURAL - not singular.
+
+With NO parameter, this plural @b{targets} command lists all known
+targets in a human friendly form.
+
+With a parameter, this plural @b{targets} command sets the current
+target to the given name. (i.e.: If there are multiple debug targets)
+
+Example:
+@verbatim
+(gdb) mon targets
+ CmdName Type Endian ChainPos State
+-- ---------- ---------- ---------- -------- ----------
+ 0: target0 arm7tdmi little 0 halted
+@end verbatim
+
+@section target COMMANDS
+@b{Note:} This command name is SINGULAR - not plural. It is used to
+manipulate specific targets, to create targets and other things.
+
+Once a target is created, a TARGETNAME (object) command is created;
+see below for details.
+
+The TARGET command accepts these sub-commands:
+@itemize @bullet
+@item @b{create} .. parameters ..
+@* creates a new target, see below for details.
+@item @b{types}
+@* Lists all supported target types (perhaps some are not yet in this document).
+@item @b{names}
+@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
+@verbatim
+ foreach t [target names] {
+ puts [format "Target: %s\n" $t]
+ }
+@end verbatim
+@item @b{current}
+@* Returns the current target. OpenOCD always has, or refers to the ``current target'' in some way.
+By default, commands like: ``mww'' (used to write memory) operate on the current target.
+@item @b{number} @b{NUMBER}
+@* Internally OpenOCD maintains a list of targets - in numerical index
+(0..N-1) this command returns the name of the target at index N.
+Example usage:
+@verbatim
+ set thename [target number $x]
+ puts [format "Target %d is: %s\n" $x $thename]
+@end verbatim
+@item @b{count}
+@* Returns the number of targets known to OpenOCD (see number above)
+Example:
+@verbatim
+ set c [target count]
+ for { set x 0 } { $x < $c } { incr x } {
+ # Assuming you have created this function
+ print_target_details $x
+ }
+@end verbatim
+
+@end itemize
+
+@section TARGETNAME (object) commands
+@b{Use:} Once a target is created, an ``object name'' that represents the
+target is created. By convention, the target name is identical to the
+tap name. In a multiple target system, one can preceed many common
+commands with a specific target name and effect only that target.
+@example
+ str912.cpu mww 0x1234 0x42
+ omap3530.cpu mww 0x5555 123
+@end example
+
+@b{Model:} The Tcl/Tk language has the concept of object commands. A
+good example is a on screen button, once a button is created a button
+has a name (a path in Tk terms) and that name is useable as a 1st
+class command. For example in Tk, one can create a button and later
+configure it like this:
+
+@example
+ # Create
+ button .foobar -background red -command @{ foo @}
+ # Modify
+ .foobar configure -foreground blue
+ # Query
+ set x [.foobar cget -background]
+ # Report
+ puts [format "The button is %s" $x]
+@end example
+
+In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
+button. Commands available as a ``target object'' are:
+
+@comment START targetobj commands.
+@itemize @bullet
+@item @b{configure} - configure the target; see Target Config/Cget Options below
+@item @b{cget} - query the target configuration; see Target Config/Cget Options below
+@item @b{curstate} - current target state (running, halt, etc.
+@item @b{eventlist}
+@* Intended for a human to see/read the currently configure target events.
+@item @b{Various Memory Commands} See the ``mww'' command elsewhere.
+@comment start memory
+@itemize @bullet
+@item @b{mww} ...
+@item @b{mwh} ...
+@item @b{mwb} ...
+@item @b{mdw} ...
+@item @b{mdh} ...
+@item @b{mdb} ...
+@comment end memory
+@end itemize
+@item @b{Memory To Array, Array To Memory}
+@* These are aimed at a machine interface to memory
+@itemize @bullet
+@item @b{mem2array ARRAYNAME WIDTH ADDRESS COUNT}
+@item @b{array2mem ARRAYNAME WIDTH ADDRESS COUNT}
+@* Where:
+@* @b{ARRAYNAME} is the name of an array variable
+@* @b{WIDTH} is 8/16/32 - indicating the memory access size
+@* @b{ADDRESS} is the target memory address
+@* @b{COUNT} is the number of elements to process
+@end itemize
+@item @b{Used during ``reset''}
+@* These commands are used internally by the OpenOCD scripts to deal
+with odd reset situations and are not documented here.
+@itemize @bullet
+@item @b{arp_examine}
+@item @b{arp_poll}
+@item @b{arp_reset}
+@item @b{arp_halt}
+@item @b{arp_waitstate}
+@end itemize
+@item @b{invoke-event} @b{EVENT-NAME}
+@* Invokes the specific event manually for the target
+@end itemize
+
+@section Target Events
+@cindex events
+@anchor{Target Events}
+At various times, certain things can happen, or you want them to happen.
+
+Examples:
+@itemize @bullet
+@item What should happen when GDB connects? Should your target reset?
+@item When GDB tries to flash the target, do you need to enable the flash via a special command?
+@item During reset, do you need to write to certain memory location to reconfigure the SDRAM?
+@end itemize
+
+All of the above items are handled by target events.
+
+To specify an event action, either during target creation, or later
+via ``$_TARGETNAME configure'' see this example.
+
+Syntactially, the option is: ``-event NAME BODY'' where NAME is a
+target event name, and BODY is a Tcl procedure or string of commands
+to execute.
+
+The programmers model is the ``-command'' option used in Tcl/Tk
+buttons and events. Below are two identical examples, the first
+creates and invokes small procedure. The second inlines the procedure.
+
+@example
+ proc my_attach_proc @{ @} @{
+ puts "RESET...."
+ reset halt
+ @}
+ mychip.cpu configure -event gdb-attach my_attach_proc
+ mychip.cpu configure -event gdb-attach @{ puts "Reset..." ; reset halt @}
+@end example
+
+@section Current Events
+The following events are available:
+@itemize @bullet
+@item @b{debug-halted}
+@* The target has halted for debug reasons (i.e.: breakpoint)
+@item @b{debug-resumed}
+@* The target has resumed (i.e.: gdb said run)
+@item @b{early-halted}
+@* Occurs early in the halt process
+@item @b{examine-end}
+@* Currently not used (goal: when JTAG examine completes)
+@item @b{examine-start}
+@* Currently not used (goal: when JTAG examine starts)
+@item @b{gdb-attach}
+@* When GDB connects
+@item @b{gdb-detach}
+@* When GDB disconnects
+@item @b{gdb-end}
+@* When the taret has halted and GDB is not doing anything (see early halt)
+@item @b{gdb-flash-erase-start}
+@* Before the GDB flash process tries to erase the flash
+@item @b{gdb-flash-erase-end}
+@* After the GDB flash process has finished erasing the flash
+@item @b{gdb-flash-write-start}
+@* Before GDB writes to the flash
+@item @b{gdb-flash-write-end}
+@* After GDB writes to the flash
+@item @b{gdb-start}
+@* Before the taret steps, gdb is trying to start/resume the target
+@item @b{halted}
+@* The target has halted
+@item @b{old-gdb_program_config}
+@* DO NOT USE THIS: Used internally
+@item @b{old-pre_resume}
+@* DO NOT USE THIS: Used internally
+@item @b{reset-assert-pre}
+@* Before reset is asserted on the tap.
+@item @b{reset-assert-post}
+@* Reset is now asserted on the tap.
+@item @b{reset-deassert-pre}
+@* Reset is about to be released on the tap
+@item @b{reset-deassert-post}
+@* Reset has been released on the tap
+@item @b{reset-end}
+@* Currently not used.
+@item @b{reset-halt-post}
+@* Currently not usd
+@item @b{reset-halt-pre}
+@* Currently not used
+@item @b{reset-init}
+@* Used by @b{reset init} command for board-specific initialization.
+This is where you would configure PLLs and clocking, set up DRAM so
+you can download programs that don't fit in on-chip SRAM, set up pin
+multiplexing, and so on.
+@item @b{reset-start}
+@* Currently not used
+@item @b{reset-wait-pos}
+@* Currently not used
+@item @b{reset-wait-pre}
+@* Currently not used
+@item @b{resume-start}
+@* Before any target is resumed
+@item @b{resume-end}
+@* After all targets have resumed
+@item @b{resume-ok}
+@* Success
+@item @b{resumed}
+@* Target has resumed
+@item @b{tap-enable}
+@* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-enable @{
+ puts "Enabling CPU"
+ ...
+@}
+@end example
+@item @b{tap-disable}
+@*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
+@example
+jtag configure DOTTED.NAME -event tap-disable @{
+ puts "Disabling CPU"
+ ...
+@}
+@end example
+@end itemize
+
+@section Target Create
+@anchor{Target Create}
+@cindex target
+@cindex target creation
+
+@example
+@b{target} @b{create} <@var{NAME}> <@var{TYPE}> <@var{PARAMS ...}>
+@end example
+@*This command creates a GDB debug target that refers to a specific JTAG tap.
+@comment START params
+@itemize @bullet
+@item @b{NAME}
+@* Is the name of the debug target. By convention it should be the tap
+DOTTED.NAME. This name is also used to create the target object
+command, and in other places the target needs to be identified.
+@item @b{TYPE}
+@* Specifies the target type, i.e.: ARM7TDMI, or Cortex-M3. Currently supported targets are:
+@comment START types
+@itemize @minus
+@item @b{arm7tdmi}
+@item @b{arm720t}
+@item @b{arm9tdmi}
+@item @b{arm920t}
+@item @b{arm922t}
+@item @b{arm926ejs}
+@item @b{arm966e}
+@item @b{cortex_m3}
+@item @b{feroceon}
+@item @b{xscale}
+@item @b{arm11}
+@item @b{mips_m4k}
+@comment end TYPES
+@end itemize
+@item @b{PARAMS}
+@*PARAMs are various target configuration parameters. The following ones are mandatory:
+@comment START mandatory
+@itemize @bullet
+@item @b{-endian big|little}
+@item @b{-chain-position DOTTED.NAME}
+@comment end MANDATORY
+@end itemize
+@comment END params
+@end itemize
+
+@section Target Config/Cget Options
+These options can be specified when the target is created, or later
+via the configure option or to query the target via cget.
+
+You should specify a working area if you can; typically it uses some
+on-chip SRAM. Such a working area can speed up many things, including bulk
+writes to target memory; flash operations like checking to see if memory needs
+to be erased; GDB memory checksumming; and may help perform otherwise
+unavailable operations (like some coprocessor operations on ARM7/9 systems).
+@itemize @bullet
+@item @b{-type} - returns the target type
+@item @b{-event NAME BODY} see Target events
+@item @b{-work-area-virt [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is active.
+@item @b{-work-area-phys [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is inactive.
+@item @b{-work-area-size [ADDRESS]} specify/set the work area
+@item @b{-work-area-backup [0|1]} does the work area get backed up;
+by default, it doesn't. When possible, use a working_area that doesn't
+need to be backed up, since performing a backup slows down operations.
+@item @b{-endian [big|little]}
+@item @b{-variant [NAME]} some chips have variants OpenOCD needs to know about
+@item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
+@end itemize
+Example:
+@example
+ for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
+ set name [target number $x]
+ set y [$name cget -endian]
+ set z [$name cget -type]
+ puts [format "Chip %d is %s, Endian: %s, type: %s" $x $y $z]
+ @}
+@end example
+
+@section Target Variants
+@itemize @bullet
+@item @b{arm7tdmi}
+@* Unknown (please write me)
+@item @b{arm720t}
+@* Unknown (please write me) (similar to arm7tdmi)
+@item @b{arm9tdmi}
+@* Variants: @option{arm920t}, @option{arm922t} and @option{arm940t}
+This enables the hardware single-stepping support found on these
+cores.
+@item @b{arm920t}
+@* None.
+@item @b{arm966e}
+@* None (this is also used as the ARM946)
+@item @b{cortex_m3}
+@* use variant <@var{-variant lm3s}> when debugging Luminary lm3s targets. This will cause
+OpenOCD to use a software reset rather than asserting SRST to avoid a issue with clearing
+the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest, these revisions will
+be detected and the normal reset behaviour used.
+@item @b{xscale}
+@* Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},@option{pxa250}, @option{pxa255}, @option{pxa26x}.
+@item @b{arm11}
+@* Supported variants are @option{arm1136}, @option{arm1156}, @option{arm1176}
+@item @b{mips_m4k}
+@* Use variant @option{ejtag_srst} when debugging targets that do not
+provide a functional SRST line on the EJTAG connector. This causes
+OpenOCD to instead use an EJTAG software reset command to reset the
+processor. You still need to enable @option{srst} on the reset
+configuration command to enable OpenOCD hardware reset functionality.
+@comment END variants
+@end itemize
+@section working_area - Command Removed
+@cindex working_area
+@*@b{Please use the ``$_TARGETNAME configure -work-area-... parameters instead}
+@* This documentation remains because there are existing scripts that
+still use this that need to be converted.
+@example
+ working_area target# address size backup| [virtualaddress]
+@end example
+@* The target# is a the 0 based target numerical index.
+
+@node Flash Configuration
+@chapter Flash programming
+@cindex Flash Configuration
+
+OpenOCD has different commands for NOR and NAND flash;
+the ``flash'' command works with NOR flash, while
+the ``nand'' command works with NAND flash.
+This partially reflects different hardware technologies:
+NOR flash usually supports direct CPU instruction and data bus access,
+while data from a NAND flash must be copied to memory before it can be
+used. (SPI flash must also be copied to memory before use.)
+However, the documentation also uses ``flash'' as a generic term;
+for example, ``Put flash configuration in board-specific files''.
+
+@b{Note:} As of 28/nov/2008 OpenOCD does not know how to program a SPI
+flash that a micro may boot from. Perhaps you, the reader, would like to
+contribute support for this.
+
+Flash Steps:
+@enumerate
+@item Configure via the command @b{flash bank}
+@* Normally this is done in a configuration file.
+@item Operate on the flash via @b{flash SOMECOMMAND}
+@* Often commands to manipulate the flash are typed by a human, or run
+via a script in some automated way. For example: To program the boot
+flash on your board.
+@item GDB Flashing
+@* Flashing via GDB requires the flash be configured via ``flash
+bank'', and the GDB flash features be enabled.
+@xref{GDB Configuration}.
+@end enumerate
+
+@section Flash commands
+@cindex Flash commands
+@subsection flash banks
+@b{flash banks}
+@cindex flash banks
+@*List configured flash banks
+@*@b{NOTE:} the singular form: 'flash bank' is used to configure the flash banks.
+@subsection flash info
+@b{flash info} <@var{num}>
+@cindex flash info
+@*Print info about flash bank <@option{num}>
+@subsection flash probe
+@b{flash probe} <@var{num}>
+@cindex flash probe
+@*Identify the flash, or validate the parameters of the configured flash. Operation
+depends on the flash type.
+@subsection flash erase_check
+@b{flash erase_check} <@var{num}>
+@cindex flash erase_check
+@*Check erase state of sectors in flash bank <@var{num}>. This is the only operation that
+updates the erase state information displayed by @option{flash info}. That means you have
+to issue an @option{erase_check} command after erasing or programming the device to get
+updated information.
+@subsection flash protect_check
+@b{flash protect_check} <@var{num}>
+@cindex flash protect_check
+@*Check protection state of sectors in flash bank <num>.
+@option{flash erase_sector} using the same syntax.
+@subsection flash erase_sector
+@b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
+@cindex flash erase_sector
+@anchor{flash erase_sector}
+@*Erase sectors at bank <@var{num}>, starting at sector <@var{first}> up to and including
+<@var{last}>. Sector numbering starts at 0. Depending on the flash type, erasing may
+require the protection to be disabled first (e.g. Intel Advanced Bootblock flash using
+the CFI driver).
+@subsection flash erase_address
+@b{flash erase_address} <@var{address}> <@var{length}>
+@cindex flash erase_address
+@*Erase sectors starting at <@var{address}> for <@var{length}> bytes
+@subsection flash write_bank
+@b{flash write_bank} <@var{num}> <@var{file}> <@var{offset}>
+@cindex flash write_bank
+@anchor{flash write_bank}
+@*Write the binary <@var{file}> to flash bank <@var{num}>, starting at
+<@option{offset}> bytes from the beginning of the bank.
+@subsection flash write_image
+@b{flash write_image} [@var{erase}] <@var{file}> [@var{offset}] [@var{type}]
+@cindex flash write_image
+@anchor{flash write_image}
+@*Write the image <@var{file}> to the current target's flash bank(s). A relocation
+[@var{offset}] can be specified and the file [@var{type}] can be specified
+explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf}
+(ELF file) or @option{s19} (Motorola s19). Flash memory will be erased prior to programming
+if the @option{erase} parameter is given.
+@subsection flash protect
+@b{flash protect} <@var{num}> <@var{first}> <@var{last}> <@option{on}|@option{off}>
+@cindex flash protect
+@*Enable (@var{on}) or disable (@var{off}) protection of flash sectors <@var{first}> to
+<@var{last}> of @option{flash bank} <@var{num}>.
+
+@subsection mFlash commands
+@cindex mFlash commands
+@itemize @bullet
+@item @b{mflash probe}
+@cindex mflash probe
+Probe mflash.
+@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
+@cindex mflash write
+Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
+<@var{offset}> bytes from the beginning of the bank.
+@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
+@cindex mflash dump
+Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
+to a <@var{file}>.
+@end itemize
+
+@section flash bank command
+The @b{flash bank} command is used to configure one or more flash chips (or banks in OpenOCD terms)
+
+@example
+@b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
+<@var{bus_width}> <@var{target}> [@var{driver_options ...}]
+@end example
+@cindex flash bank
+@*Configures a flash bank at <@var{base}> of <@var{size}> bytes and <@var{chip_width}>
+and <@var{bus_width}> bytes using the selected flash <driver>.
+
+@subsection External Flash - cfi options
+@cindex cfi options
+CFI flashes are external flash chips - often they are connected to a
+specific chip select on the CPU. By default, at hard reset, most
+CPUs have the ablity to ``boot'' from some flash chip - typically
+attached to the CPU's CS0 pin.
+
+For other chip selects: OpenOCD does not know how to configure, or
+access a specific chip select. Instead you, the human, might need to
+configure additional chip selects via other commands (like: mww) , or
+perhaps configure a GPIO pin that controls the ``write protect'' pin
+on the flash chip.
+
+@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
+<@var{target}> [@var{jedec_probe}|@var{x16_as_x8}]
+@*CFI flashes require the name or number of the target they're connected to
+as an additional
+argument. The CFI driver makes use of a working area (specified for the target)
+to significantly speed up operation.