+@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.
+