aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorzwelch <zwelch@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-05-30 01:32:19 +0000
committerzwelch <zwelch@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-05-30 01:32:19 +0000
commitd00a5cfe97452f9d72aeff31d00fac5979add0ea (patch)
treed3c7e74dac9421011e5084a576598fc1993dc38d /doc
parentebcde562d9903a257a3b40a79c94e1010e5b5fc2 (diff)
downloadriscv-openocd-d00a5cfe97452f9d72aeff31d00fac5979add0ea.zip
riscv-openocd-d00a5cfe97452f9d72aeff31d00fac5979add0ea.tar.gz
riscv-openocd-d00a5cfe97452f9d72aeff31d00fac5979add0ea.tar.bz2
David Brownell <david-b@pacbell.net>:
Make it so the magic "reset_config" keywords can be provided in any order. This eliminates needless error paths, and makes it easier to define things at the right level (adapter, board, target). It also includes two other behavioral changes: (1) When "handle_reset_config" sees a parameter error, it exits without changing anything. This is best viewed as a bugfix. (Old behavior: restore defaults, even if they weren't previously active.) (2) Only the behaviors that were explicitly specified get changed. (Old behavior: everything else gets reset to the "default".) So for example you can now specify SRST drive requirements without saying anything about the three unrelated topics you previously had to specify. That second one might cause confusion for any configs that end up calling "reset_config" twice, so it will deserve to be called out in the release notes. (There were no such configurations in the current OpenOCD source tree.) Update docs accordingly. Note that at least some versions of the texi-to-html tools can't handle "@xref{with spaces}", but those work properly in PDF and in the info files. git-svn-id: svn://svn.berlios.de/openocd/trunk@1944 b42882b7-edfa-0310-969c-e2dbd0fdcd60
Diffstat (limited to 'doc')
-rw-r--r--doc/openocd.texi75
1 files changed, 57 insertions, 18 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 2e4f992..b5c325d 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1574,9 +1574,13 @@ jtag_rclk 3000
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}.)
Please see the various board files for examples.
-@b{Note} to maintainers and integrators:
+@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
@@ -1587,6 +1591,7 @@ 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.
+@end quotation
@section Types of Reset
@@ -1671,11 +1676,18 @@ Use the @command{reset_config} @var{trst_type} and
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.
+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
@@ -1691,31 +1703,58 @@ 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]]]
+@deffn {Command} reset_config mode_flag ...
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{mode_flag} options can be specified in any order, but only one
+of each type -- @var{signals}, @var{combination}, @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}).
+
+@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 or TRST through the JTAG connector,
+you must declare that or else those signals will not be used.
+@end quotation
The @var{combination} is an optional value specifying broken reset
-signal implementations. @option{srst_pulls_trst} states that the
+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}. The default behaviour if no option given is
-@option{separate}.
+@option{trst_pulls_srst}.
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.
+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 JTAGAccelerator. Also, they are necessarily ignored if the
+relevant signal (TRST or SRST) is not connected.
+
+Possible @var{trst_type} driver modes for the test reset signal (TRST)
+are @option{trst_push_pull} (default) 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.
+
+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.
@end deffn