+@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
+@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
+@item @b{-ircapture NUMBER} - the ID code capture command.
+@item @b{-irmask NUMBER} - the corrisponding mask for the ir register.
+@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.
+
+FIXME: The IDCODE - this was not used in the old code, it should be?
+Right? -Duane.
+@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 4th parameter is the
+``irmask'' The new syntax requires named prefixes, and supports
+additional options, for example ``-irmask 4'' Please refer to the
+@b{jtag newtap} command for deails.
+@example
+OLD: jtag_device 8 0x01 0x0e3 0xfe
+NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0xe3 -irmask 0xfe
+@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 OpenOCDs 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 return 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.
+