+@end deffn
+
+@deffn Command {parport_toggling_time} [nanoseconds]
+Displays how many nanoseconds the hardware needs to toggle TCK;
+the parport driver uses this value to obey the
+@command{jtag_khz} configuration.
+When the optional @var{nanoseconds} parameter is given,
+that setting is changed before displaying the current value.
+
+The default setting should work reasonably well on commodity PC hardware.
+However, you may want to calibrate for your specific hardware.
+@quotation Tip
+To measure the toggling time with a logic analyzer or a digital storage
+oscilloscope, follow the procedure below:
+@example
+> parport_toggling_time 1000
+> jtag_khz 500
+@end example
+This sets the maximum JTAG clock speed of the hardware, but
+the actual speed probably deviates from the requested 500 kHz.
+Now, measure the time between the two closest spaced TCK transitions.
+You can use @command{runtest 1000} or something similar to generate a
+large set of samples.
+Update the setting to match your measurement:
+@example
+> parport_toggling_time <measured nanoseconds>
+@end example
+Now the clock speed will be a better match for @command{jtag_khz rate}
+commands given in OpenOCD scripts and event handlers.
+
+You can do something similar with many digital multimeters, but note
+that you'll probably need to run the clock continuously for several
+seconds before it decides what clock rate to show. Adjust the
+toggling time up or down until the measured clock rate is a good
+match for the jtag_khz rate you specified; be conservative.
+@end quotation
+@end deffn
+
+@deffn {Config Command} {parport_write_on_exit} (on|off)
+This will configure the parallel driver to write a known
+cable-specific value to the parallel interface on exiting OpenOCD
+@end deffn
+
+For example, the interface configuration file for a
+classic ``Wiggler'' cable might look something like this:
+
+@example
+interface parport
+parport_port 0xc8b8
+parport_cable wiggler
+@end example
+@end deffn
+
+@deffn {Interface Driver} {presto}
+ASIX PRESTO USB JTAG programmer.
+@c command: presto_serial str
+@c sets serial number
+@end deffn
+
+@deffn {Interface Driver} {rlink}
+Raisonance RLink USB adapter
+@end deffn
+
+@deffn {Interface Driver} {usbprog}
+usbprog is a freely programmable USB adapter.
+@end deffn
+
+@deffn {Interface Driver} {vsllink}
+vsllink is part of Versaloon which is a versatile USB programmer.
+
+@quotation Note
+This defines quite a few driver-specific commands,
+which are not currently documented here.
+@end quotation
+@end deffn
+
+@deffn {Interface Driver} {ZY1000}
+This is the Zylin ZY1000 JTAG debugger.
+
+@quotation Note
+This defines some driver-specific commands,
+which are not currently documented here.
+@end quotation
+
+@deffn Command power [@option{on}|@option{off}]
+Turn power switch to target on/off.
+No arguments: print status.
+@end deffn
+
+@end deffn
+
+@anchor{JTAG Speed}
+@section 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, and the scan chain verification which
+follows reset, can be adjusted using a @code{reset-start}
+target event handler.
+It can then be reconfigured to a faster speed by a
+@code{reset-init} target event handler after it reprograms those
+CPU clocks, or manually (if something else, such as a boot loader,
+sets up those clocks).
+@xref{Target Events}.
+When the initial low JTAG speed is a chip characteristic, perhaps
+because of a required oscillator speed, provide such a handler
+in the target config file.
+When that speed is a function of a board-specific characteristic
+such as which speed oscillator is used, it belongs in the board
+config file instead.
+In both cases it's safest to also set the initial JTAG clock rate
+to that same slow speed, so that OpenOCD never starts up using a
+clock speed that's faster than the scan chain can support.
+
+@example
+jtag_rclk 3000
+$_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @}
+@end example
+
+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.
+
+Chip data sheets generally include a top JTAG clock rate.
+The actual rate is often a function of a CPU core clock,
+and is normally less than that peak rate.
+For example, most ARM cores accept at most one sixth of the CPU clock.
+
+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 adaptive clocking
+@cindex RTCK
+This Tcl proc (defined in @file{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.
+Resets also interact with @var{reset-init} event handlers,
+which do things like setting up clocks and DRAM, and
+JTAG clock rates. (@xref{JTAG Speed}.)
+They can also interact with JTAG routers.
+Please see the various board files for examples.
+
+@quotation 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
+user configuration file will need to override parts of
+the reset configuration provided by other files.
+@end quotation
+
+@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}.)
+
+@anchor{SRST and TRST Issues}
+@section SRST and TRST 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 either 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.
+Missing TRST is not a problem, since JTAG level resets can
+be triggered using with TMS signaling.
+
+@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.
+
+@item @emph{Special initialization} ... Targets sometimes need
+special JTAG initialization sequences to handle chip-specific
+issues (not limited to errata).
+For example, certain JTAG commands might need to be issued while
+the system as a whole is in a reset state (SRST active)
+but the JTAG scan chain is usable (TRST inactive).
+Many systems treat combined assertion of SRST and TRST as a
+trigger for a harder reset than SRST alone.
+Such custom reset handling is discussed later in this chapter.
+@end itemize
+
+There can also be other issues.
+Some devices don't fully conform to the JTAG specifications.
+Trivial system-specific differences are common, such as
+SRST and TRST using slightly different names.
+There are also vendors who distribute key JTAG documentation for
+their chips only to developers who have signed a Non-Disclosure
+Agreement (NDA).
+
+Sometimes there are chip-specific extensions like a requirement to use
+the normally-optional TRST signal (precluding use of JTAG adapters which
+don't pass TRST through), or needing extra steps to complete a TAP reset.
+
+In short, SRST and especially TRST handling may be very finicky,
+needing to cope with both architecture and board specific constraints.
+
+@section Commands for Handling Resets
+
+@deffn {Command} jtag_nsrst_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nSRST (active-low system reset) before
+allowing it to be deasserted.
+@end deffn
+
+@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_assert_width milliseconds
+Minimum amount of time (in milliseconds) OpenOCD should wait
+after asserting nTRST (active-low JTAG TAP reset) before
+allowing it to be deasserted.
+@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 mode_flag ...
+This command displays or modifies the reset configuration
+of your combination of JTAG board and target in target
+configuration scripts.
+
+Information earlier in this section describes the kind of problems
+the command is intended to address (@pxref{SRST and TRST Issues}).
+As a rule this command belongs only in board config files,
+describing issues like @emph{board doesn't connect TRST};
+or in user config files, addressing limitations derived
+from a particular combination of interface and board.
+(An unlikely example would be using a TRST-only adapter
+with a board that only wires up SRST.)
+
+The @var{mode_flag} options can be specified in any order, but only one
+of each type -- @var{signals}, @var{combination},
+@var{gates},
+@var{trst_type},
+and @var{srst_type} -- may be specified at a time.
+If you don't provide a new value for a given type, its previous
+value (perhaps the default) is unchanged.
+For example, this means that you don't need to say anything at all about
+TRST just to declare that if the JTAG adapter should want to drive SRST,
+it must explicitly be driven high (@option{srst_push_pull}).
+
+@itemize
+@item
+@var{signals} can specify which of the reset signals are connected.
+For example, If the JTAG interface provides SRST, but the board doesn't
+connect that signal properly, then OpenOCD can't use it.
+Possible values are @option{none} (the default), @option{trst_only},
+@option{srst_only} and @option{trst_and_srst}.
+
+@quotation Tip
+If your board provides SRST and/or TRST through the JTAG connector,
+you must declare that so those signals can be used.
+@end quotation
+
+@item
+The @var{combination} is an optional value specifying broken reset
+signal implementations.
+The default behaviour if no option given is @option{separate},
+indicating everything behaves normally.
+@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}.
+
+@item
+The @var{gates} tokens control flags that describe some cases where
+JTAG may be unvailable during reset.
+@option{srst_gates_jtag} (default)
+indicates that asserting SRST gates the
+JTAG clock. This means that no communication can happen on JTAG
+while SRST is asserted.
+Its converse is @option{srst_nogate}, indicating that JTAG commands
+can safely be issued while SRST is active.
+@end itemize
+
+The optional @var{trst_type} and @var{srst_type} parameters allow the
+driver mode of each reset line to be specified. These values only affect
+JTAG interfaces with support for different driver modes, like the Amontec
+JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the
+relevant signal (TRST or SRST) is not connected.
+
+@itemize
+@item
+Possible @var{trst_type} driver modes for the test reset signal (TRST)
+are the default @option{trst_push_pull}, and @option{trst_open_drain}.
+Most boards connect this signal to a pulldown, so the JTAG TAPs
+never leave reset unless they are hooked up to a JTAG adapter.
+
+@item
+Possible @var{srst_type} driver modes for the system reset signal (SRST)
+are the default @option{srst_open_drain}, and @option{srst_push_pull}.
+Most boards connect this signal to a pullup, and allow the
+signal to be pulled low by various events including system
+powerup and pressing a reset button.