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.
---
doc/openocd.texi | 98 +++++++++++++++++++++++++++++++---------------------
src/jtag/ft2232.c | 2 -
src/jtag/jtag.c | 5 +-
3 files changed, 63 insertions(+), 42 deletions(-)
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.
---
doc/openocd.texi | 98 +++++++++++++++++++++++++++++++---------------------
src/jtag/ft2232.c | 2 -
src/jtag/jtag.c | 5 +-
3 files changed, 63 insertions(+), 42 deletions(-)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1493,53 +1493,58 @@ The OpenOCD default value is 2 and for s
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
+...@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.
-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)
+The speed used during reset can be adjusted using pre_reset
+and post_reset event handlers.
+...@xref{target Events}.
-Speed 0 (khz) selects RTCK method. A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+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.
-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.
+...@b{note:} Script writers should consider using @command{jtag_rclk}
+instead of @command{jtag_khz}.
-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.
+...@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.
-...@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.
+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 rese
@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
@*
--- a/src/jtag/ft2232.c
+++ b/src/jtag/ft2232.c
@@ -446,7 +446,7 @@ static int ft2232_khz(int khz, int* jtag
{
if (khz==0)
{
- LOG_ERROR("RCLK not supported");
+ LOG_DEBUG("RTCK not supported");
return ERROR_FAIL;
}
--- a/src/jtag/jtag.c
+++ b/src/jtag/jtag.c
@@ -2315,9 +2315,10 @@ int jtag_register_commands(struct comman
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,
_______________________________________________
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
