From ad8f1b42956bdf463ce85ed741e1f62ba91ae62f Mon Sep 17 00:00:00 2001 From: zwelch Date: Sun, 24 May 2009 21:13:29 +0000 Subject: [PATCH] David Brownell : 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 --- doc/openocd.texi | 98 ++++++++++++++++++++++++++++------------------- src/jtag/ft2232.c | 2 +- src/jtag/jtag.c | 5 ++- 3 files changed, 63 insertions(+), 42 deletions(-) diff --git a/doc/openocd.texi b/doc/openocd.texi index cf01a94c0..261c41d1d 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 +@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 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 43c6f1692..4239c2d0b 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 fce0eb8a6..56a8075b1 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 "); register_command(cmd_ctx, NULL, "reset_config", handle_reset_config_command,