[Openocd-svn] r1913 - trunk/doc

[<zw...@ma...>]

Author: zwelch
Date: 2009-05-26 02:23:23 +0200 (Tue, 26 May 2009)
New Revision: 1913

Modified:
   trunk/doc/openocd.texi
Log:
David Brownell <da...@pa...>:

Update the "Reset Configuration" information in the User's guide:

 - Convert to @deffn syntax
 - Move tutorial text from command descriptions into new sections
 - Describe several different types of JTAG-visible reset
 - Expand descriptions of configuration tweaks for SRST and TRST 
 - Link to the "reset" command, and vice versa
 - Bugfix the "reset_config" description (it didn't match the code)

Plus, be more proscriptive:  do it in board config files, except for
the oddball cases where that won't work. (Current target.cfg files
seem to have much goofage there; several seem board-specific.)


Modified: trunk/doc/openocd.texi
===================================================================
--- trunk/doc/openocd.texi	2009-05-25 15:56:15 UTC (rev 1912)
+++ trunk/doc/openocd.texi	2009-05-26 00:23:23 UTC (rev 1913)
@@ -1551,67 +1551,133 @@
 @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.
+configuration. This can also be quite confusing.
+Please see the various board files for examples.
 
-@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.
+@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 jtag_ntrst_delay <@var{ms}>
-@cindex jtag_ntrst_delay
-@*Same @b{jtag_nsrst_delay}, but for nTRST  
+@section Types of Reset
 
-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.
+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.
 
-@section reset_config
+@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
 
-@b{Note:} To maintainers 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.}
+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}.)
 
-@* @b{Problems:} 
-@enumerate
-@item Every JTAG Dongle is slightly different, some dongles implement 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 implement 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 on your board vendor, chip vendor, etc., these
-signals may have slightly different names. 
+@section SRST and TRST Signal Issues
 
-OpenOCD defines these signals in these terms:
+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 @b{TRST} - is Tap Reset - and should reset only the TAP.
-@item @b{SRST} - is System Reset - typically equal to a reset push button.
+
+@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
 
-The Command:
+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.
 
-@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
+@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}.
 
-[@var{combination}] is an optional value specifying broken reset
+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
@@ -1621,19 +1687,16 @@
 @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
+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
 
-@comment - end command
-@end itemize
 
-
-
 @node Tap Creation
 @chapter Tap Creation
 @cindex tap creation
@@ -3053,11 +3116,14 @@
 @cindex step
 @*Single-step the target at its current code position, or at an optional address. 
 
+@anchor{Reset Command}
 @subsection reset [@option{run}|@option{halt}|@option{init}]
 @cindex reset
-@*Perform a hard-reset. The optional parameter specifies what should happen after the reset.
-
-With no arguments a "reset run" is executed
+@*Perform a hard-reset. The optional parameter specifies what should
+happen after the reset.
+If there is no parameter, a @command{reset run} is executed.
+The other options will not work on all systems.
+@xref{Reset Configuration}.
 @itemize @minus
 @item @b{run}
 @cindex reset run