summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorzwelch <zwelch@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-05-24 21:13:29 +0000
committerzwelch <zwelch@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-05-24 21:13:29 +0000
commitad8f1b42956bdf463ce85ed741e1f62ba91ae62f (patch)
tree37a88aedbeb7ce6f63f3f08280f664a9c661cc85
parent5ecae346cc675cf269d5e3371a7d05181d570cdb (diff)
downloadopenocd+libswd-ad8f1b42956bdf463ce85ed741e1f62ba91ae62f.tar.gz
openocd+libswd-ad8f1b42956bdf463ce85ed741e1f62ba91ae62f.tar.bz2
openocd+libswd-ad8f1b42956bdf463ce85ed741e1f62ba91ae62f.tar.xz
openocd+libswd-ad8f1b42956bdf463ce85ed741e1f62ba91ae62f.zip
David Brownell <david-b@pacbell.net>:
Doc (mostly) update for jtag_khz: - switch to @deffn syntax - add entry for "jtag_rclk" - move deprecated "jtag_speed" into collection of deprecated calls And for ft2232, don't be the only adapter to *log* an error if RTCK is requested; it's already reported properly, like any other nonfatal command parameter. "jtag_rclk" just works as expected, without any scarey messages. git-svn-id: svn://svn.berlios.de/openocd/trunk@1910 b42882b7-edfa-0310-969c-e2dbd0fdcd60
-rw-r--r--doc/openocd.texi108
-rw-r--r--src/jtag/ft2232.c2
-rw-r--r--src/jtag/jtag.c5
3 files changed, 68 insertions, 47 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi
index cf01a94c..261c41d1 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1493,53 +1493,58 @@ The OpenOCD default value is 2 and for some systems a value of 10 has proved use
Currently, there are no options available for the ep93xx interface.
@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 initialisation process (i.e.: (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.
+@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 RCLK is not supported
- jtag_rclk 3000
+# Fall back to 3mhz if RTCK is not supported
+jtag_rclk 3000
@end example
-
-@item @b{DEPRECATED} @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
-@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
-@comment end speed list.
-@end itemize
-
-@comment END command list
-@end itemize
+@end defun
@node Reset Configuration
@chapter Reset Configuration
@@ -3696,6 +3701,20 @@ and @option{target cortex_m3 little reset_halt 0}.
@item @b{flash auto_erase}
@cindex flash auto_erase
@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
+
+@item @b{jtag_speed} value
+@*@xref{JTAG Speed}.
+Usually, a value of zero means maximum
+speed. The actual effect of this option depends on the JTAG interface used.
+@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
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
+@comment end speed list.
+@end itemize
+
@item @b{load_binary}
@cindex load_binary
@*use @option{load_image} command with same args. @xref{load_image}.
@@ -3724,6 +3743,7 @@ halt
@cindex faq
@enumerate
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
+@anchor{FAQ RTCK}
@cindex RTCK
@cindex adaptive clocking
@*
diff --git a/src/jtag/ft2232.c b/src/jtag/ft2232.c
index 43c6f169..4239c2d0 100644
--- a/src/jtag/ft2232.c
+++ b/src/jtag/ft2232.c
@@ -446,7 +446,7 @@ static int ft2232_khz(int khz, int* jtag_speed)
{
if (khz==0)
{
- LOG_ERROR("RCLK not supported");
+ LOG_DEBUG("RTCK not supported");
return ERROR_FAIL;
}
diff --git a/src/jtag/jtag.c b/src/jtag/jtag.c
index fce0eb8a..56a8075b 100644
--- a/src/jtag/jtag.c
+++ b/src/jtag/jtag.c
@@ -2315,9 +2315,10 @@ int jtag_register_commands(struct command_context_s *cmd_ctx)
register_command(cmd_ctx, NULL, "interface", handle_interface_command,
COMMAND_CONFIG, "try to configure interface");
register_command(cmd_ctx, NULL, "jtag_speed", handle_jtag_speed_command,
- COMMAND_ANY, "set jtag speed (if supported)");
+ COMMAND_ANY, "(DEPRECATED) set jtag speed (if supported)");
register_command(cmd_ctx, NULL, "jtag_khz", handle_jtag_khz_command,
- COMMAND_ANY, "same as jtag_speed, except it takes maximum khz as arguments. 0 KHz = RTCK.");
+ COMMAND_ANY, "set maximum jtag speed (if supported); "
+ "parameter is maximum khz, or 0 for adaptive clocking (RTCK).");
register_command(cmd_ctx, NULL, "jtag_device", handle_jtag_device_command,
COMMAND_CONFIG, "jtag_device <ir_length> <ir_expected> <ir_mask>");
register_command(cmd_ctx, NULL, "reset_config", handle_reset_config_command,