+@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 summery the board files should contain (if present)
+
+@enumerate
+@item External flash configuration (ie: the flash on CS0)
+@item SDRAM configuration (size, speed, etc)
+@item Board specific IO configuration (ie: 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 summery 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 OnChip 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 this will help pin point
+problem 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.
+
+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 temporal 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 breif the names you should use are:
+
+@itemize @bullet
+@item @b{tap}
+@item @b{cpu}
+@item @b{flash}
+@item @b{bs}
+@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 snippits of code to program flash chips.
+
+If the chip includes an 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
+inaccessable 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 - enable it.
+
+If the chip has an ARM ``vector catch'' feature - by defeault 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.
+
+@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 the BOOT flash on
+Chip Select 0). The BOOT 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 vrs 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.2MEG 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 interpretor today (28/nov/2008) is a mixture of (newer)
+JIM-Tcl commands, and (older) the orginal command interpretor.
+
+@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
+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 init
+@cindex 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 - the init command must occur before
+the memory read/write commands.
+
+@section TCP/IP Ports
+@itemize @bullet
+@item @b{telnet_port} <@var{number}>
+@cindex telnet_port
+@*Intended for a human. Port on which to listen for incoming telnet connections.
+
+@item @b{tcl_port} <@var{number}>
+@cindex tcl_port
+@*Intended as a machine interface. Port on which to listen for
+incoming TCL syntax. This port is intended as a simplified RPC
+connection that can be used by clients to issue commands and get the
+output from the TCL engine.
+
+@item @b{gdb_port} <@var{number}>
+@cindex gdb_port
+@*First port on which to listen 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.
+@end itemize
+
+@section GDB Items
+@itemize @bullet
+@item @b{gdb_breakpoint_override} <@var{hard|soft|disabled}>
+@cindex gdb_breakpoint_override
+@anchor{gdb_breakpoint_override}
+@*Force breakpoint type for gdb 'break' commands.
+The raison d'etre for this option is to support GDB GUI's without
+a hard/soft breakpoint concept where the default OpenOCD and
+GDB behaviour is not sufficient. Note that GDB will use 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.
+
+@item @b{gdb_detach} <@var{resume|reset|halt|nothing}>
+@cindex gdb_detach
+@*Configures what OpenOCD will do when gdb detaches from the daeman.
+Default behaviour is <@var{resume}>
+
+@item @b{gdb_memory_map} <@var{enable|disable}>
+@cindex gdb_memory_map
+@*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. @option{gdb_flash_program enable} will also need enabling
+for flash programming to work.
+Default behaviour is <@var{enable}>
+@xref{gdb_flash_program}.
+
+@item @b{gdb_flash_program} <@var{enable|disable}>
+@cindex gdb_flash_program
+@anchor{gdb_flash_program}
+@*Set to <@var{enable}> to cause OpenOCD to program the flash memory when a
+vFlash packet is received.
+Default behaviour is <@var{enable}>
+@comment END GDB Items
+@end itemize
+
+@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 Conmmand
+
+The interface command tells OpenOCD what type of jtag dongle you are
+using. Depending upon 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
+@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, eg.
+@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 packages 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
+@itemize @bullet
+@item @b{jtag_khz} <@var{reset speed kHz}>
+@cindex jtag_khz
+
+It is debatable if this command belongs here - or in a board
+configuration file. In fact, in some situations the jtag speed is
+changed during the target initialization process (ie: (1) slow at
+reset, (2) program the cpu clocks, (3) run fast)
+
+Speed 0 (khz) selects RTCK method. A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+
+Not all interfaces support ``rtck''. If the interface device can not
+support the rate asked for, or can not translate from kHz to
+jtag_speed, then an error is returned.
+
+Make sure the jtag clock is no more than @math{1/6th × CPU-Clock}. This is
+especially true for synthesized cores (-S). Also see RTCK.
+
+@b{NOTE: Script writers} If the target chip requires/uses RTCK -
+please use the command: 'jtag_rclk FREQ'. This TCL proc (in
+startup.tcl) attempts to enable RTCK, if that fails it falls back to
+the specified frequency.
+
+@example
+ # Fall back to 3mhz if RCLK is not supported
+ jtag_rclk 3000
+@end example
+
+@item @b{DEPRICATED} @b{jtag_speed} - please use jtag_khz above.
+@cindex jtag_speed
+@*Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum
+speed. The actual effect of this option depends on the JTAG interface used.
+
+The speed used during reset can be adjusted using setting jtag_speed during
+pre_reset and post_reset events.
+@itemize @minus
+
+@item wiggler: maximum speed / @var{number}
+@item ft2232: 6MHz / (@var{number}+1)
+@item amt jtagaccel: 8 / 2**@var{number}
+@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
+@comment end speed list.
+@end itemize
+
+@comment END command list
+@end itemize
+
+@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 example.
+
+@section jtag_nsrst_delay <@var{ms}>
+@cindex jtag_nsrst_delay
+@*How long (in milliseconds) OpenOCD should wait after deasserting
+nSRST before starting new JTAG operations.
+
+@section jtag_ntrst_delay <@var{ms}>
+@cindex jtag_ntrst_delay
+@*Same @b{jtag_nsrst_delay}, but for nTRST
+
+The jtag_n[st]rst_delay options are useful if reset circuitry (like a
+big resistor/capacitor, reset supervisor, or on-chip features). This
+keeps the signal asserted for some time after the external reset got
+deasserted.
+
+@section reset_config
+
+@b{Note:} To maintainer types and integrators. Where exactly the
+``reset configuration'' goes is a good question. It touches several
+things at once. In the end, if you have a board file - the board file
+should define it and assume 100% that the DONGLE supports
+anything. However, that does not mean the target should not also make
+not of something the silicon vendor has done inside the
+chip. @i{Grr.... nothing is every pretty.}
+
+@* @b{Problems:}
+@enumerate
+@item Every JTAG Dongle is slightly different, some dongles impliment reset differently.
+@item Every board is also slightly different; some boards tie TRST and SRST together.
+@item Every chip is slightly different; some chips internally tie the two signals together.
+@item Some may not impliment all of the signals the same way.
+@item Some signals might be push-pull, others open-drain/collector.
+@end enumerate
+@b{Best Case:} OpenOCD can hold the SRST (push-button-reset), then
+reset the TAP via TRST and send commands through the JTAG tap to halt
+the CPU at the reset vector before the 1st instruction is executed,
+and finally release the SRST signal.
+@*Depending upon your board vendor, your chip vendor, etc, these
+signals may have slightly different names.
+
+OpenOCD defines these signals in these terms:
+@itemize @bullet
+@item @b{TRST} - is Tap Reset - and should reset only the TAP.
+@item @b{SRST} - is System Reset - typically equal to a reset push button.
+@end itemize
+
+The Command:
+
+@itemize @bullet
+@item @b{reset_config} <@var{signals}> [@var{combination}] [@var{trst_type}] [@var{srst_type}]
+@cindex reset_config
+@* The @t{reset_config} command tells OpenOCD the reset configuration
+of your combination of Dongle, Board, and Chips.
+If the JTAG interface provides SRST, but the target 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}.
+
+[@var{combination}] is an optional value specifying broken reset
+signal implementations. @option{srst_pulls_trst} states that the
+testlogic 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} imples both @option{srst_pulls_trst} and
+@option{trst_pulls_srst}. The default behaviour if no option given is
+@option{separate}.
+
+The [@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.
+
+@comment - end command
+@end itemize
+
+
+
+@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 via JTAG
+@item @b{Boundry Scan} Some chips support boundry 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. 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
+tcpip. 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{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 makers 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 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.
+@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, ie: 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 syncronization problems one must face. To
+solve that problem, the JTAG Route controller was introduced. Rather
+then ``bypass'' the tap, the tap is completely removed from the
+circuit and skipped.
+
+
+From OpenOCD's view point, 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
+
+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 pural @b{targets} command sets the current
+target to the given name. (ie: If there are multiple debug targets)
+
+Example:
+@verbatim
+(gdb) mon targets
+ CmdName Type Endian ChainPos State
+-- ---------- ---------- ---------- -------- ----------
+ 0: target0 arm7tdmi little 0 halted
+@end verbatim