jtag: adapter: rework adapter related commands

currently we have different types of same command group:
- starting with adapter_*
- starting with interface*
- without adapter or interface prefix.

Since interface name is already used, we can only use "adapter" command
group by keeping old commands as well.

Change-Id: Id0a1cb63a2ea6860c67ae1e7a3a06a37ddf464f4
Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
Reviewed-on: http://openocd.zylin.com/4774
Reviewed-by: Marc Schink <dev@zapb.de>
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-by: Oleksij Rempel <linux@rempel-privat.de>

doc/openocd.texi

@@ -1574,7 +1574,7 @@ solution just avoids using that instruction with JTAG debuggers.
 If both the chip and the board support adaptive clocking,
 use the @command{jtag_rclk}
 command, in case your board is used with JTAG adapter which
-also supports it. Otherwise use @command{adapter_khz}.
+also supports it. Otherwise use @command{adapter speed}.
 Set the slow rate at the beginning of the reset sequence,
 and the faster rate as soon as the clocks are at full speed.
 
@@ -1614,12 +1614,12 @@ proc init_board @{@} @{
     reset_config trst_and_srst trst_pulls_srst
 
     $_TARGETNAME configure -event reset-start @{
-        adapter_khz 100
+        adapter speed 100
     @}
 
     $_TARGETNAME configure -event reset-init @{
         enable_fast_clock
-        adapter_khz 10000
+        adapter speed 10000
     @}
 @}
 @end example
@@ -2344,22 +2344,22 @@ interface jlink
 Most adapters need a bit more configuration than that.
 
 
-@section Interface Configuration
+@section Adapter Configuration
 
-The interface command tells OpenOCD what type of debug adapter you are
+The @command{adapter driver} command tells OpenOCD what type of debug adapter you are
 using. Depending on the type of adapter, you may need to use one or
 more additional commands to further identify or configure the adapter.
 
-@deffn {Config Command} {interface} name
+@deffn {Config Command} {adapter driver} name
-Use the interface driver @var{name} to connect to the
+Use the adapter driver @var{name} to connect to the
 target.
 @end deffn
 
-@deffn Command {interface_list}
+@deffn Command {adapter list}
 List the debug adapter drivers that have been built into
 the running copy of OpenOCD.
 @end deffn
-@deffn Command {interface transports} transport_name+
+@deffn Command {adapter transports} transport_name+
 Specifies the transports supported by this debug adapter.
 The adapter driver builds-in similar knowledge; use this only
 when external configuration (such as jumpering) changes what
@@ -2368,7 +2368,7 @@ the hardware can support.
 
 
 
-@deffn Command {adapter_name}
+@deffn Command {adapter name}
 Returns the name of the debug adapter driver being used.
 @end deffn
 
@@ -2993,7 +2993,7 @@ you may encounter a problem.
 @deffn Command {parport_toggling_time} [nanoseconds]
 Displays how many nanoseconds the hardware needs to toggle TCK;
 the parport driver uses this value to obey the
-@command{adapter_khz} configuration.
+@command{adapter speed} configuration.
 When the optional @var{nanoseconds} parameter is given,
 that setting is changed before displaying the current value.
 
@@ -3004,7 +3004,7 @@ To measure the toggling time with a logic analyzer or a digital storage
 oscilloscope, follow the procedure below:
 @example
 > parport_toggling_time 1000
-> adapter_khz 500
+> adapter speed 500
 @end example
 This sets the maximum JTAG clock speed of the hardware, but
 the actual speed probably deviates from the requested 500 kHz.
@@ -3015,14 +3015,15 @@ Update the setting to match your measurement:
 @example
 > parport_toggling_time <measured nanoseconds>
 @end example
-Now the clock speed will be a better match for @command{adapter_khz rate}
+Now the clock speed will be a better match for @command{adapter speed}
-commands given in OpenOCD scripts and event handlers.
+command given in OpenOCD scripts and event handlers.
 
 You can do something similar with many digital multimeters, but note
 that you'll probably need to run the clock continuously for several
 seconds before it decides what clock rate to show. Adjust the
 toggling time up or down until the measured clock rate is a good
-match for the adapter_khz rate you specified; be conservative.
+match with the rate you specified in the @command{adapter speed} command;
+be conservative.
 @end quotation
 @end deffn
 
@@ -3329,10 +3330,10 @@ 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{adapter_khz}, but only for (ARM) cores and boards
+instead of @command{adapter speed}, but only for (ARM) cores and boards
 which support adaptive clocking.
 
-@deffn {Command} adapter_khz max_speed_kHz
+@deffn {Command} adapter speed 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
@@ -3462,7 +3463,7 @@ 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{adapter_nsrst_delay} and @command{jtag_ntrst_delay}
+Use the @command{adapter srst delay} and @command{jtag_ntrst_delay}
 commands to say when extra delays are needed.
 
 @item @emph{Drive type} ... Reset lines often have a pullup
@@ -3502,13 +3503,13 @@ needing to cope with both architecture and board specific constraints.
 
 @section Commands for Handling Resets
 
-@deffn {Command} adapter_nsrst_assert_width milliseconds
+@deffn {Command} adapter srst pulse_width milliseconds
 Minimum amount of time (in milliseconds) OpenOCD should wait
 after asserting nSRST (active-low system reset) before
 allowing it to be deasserted.
 @end deffn
 
-@deffn {Command} adapter_nsrst_delay milliseconds
+@deffn {Command} adapter srst 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
@@ -4889,7 +4890,7 @@ the target clocks are fully set up.)
 before @command{reset-assert-pre} is called.
 
 This is the most robust place to use @command{jtag_rclk}
-or @command{adapter_khz} to switch to a low JTAG clock rate,
+or @command{adapter speed} to switch to a low JTAG clock rate,
 when reset disables PLLs needed to use a fast clock.
 @item @b{resume-start}
 @* Before any target is resumed
@@ -10736,7 +10737,7 @@ To set the JTAG frequency use the command:
 
 @example
 # Example: 1.234MHz
-adapter_khz 1234
+adapter speed 1234
 @end example
 
 

src/jtag/adapter.c

@@ -66,7 +66,7 @@ static int jim_adapter_name(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
 	return JIM_OK;
 }
 
-COMMAND_HANDLER(interface_transport_command)
+COMMAND_HANDLER(adapter_transports_command)
 {
 	char **transports;
 	int retval;
@@ -85,12 +85,12 @@ COMMAND_HANDLER(interface_transport_command)
 	return retval;
 }
 
-COMMAND_HANDLER(handle_interface_list_command)
+COMMAND_HANDLER(handle_adapter_list_command)
 {
-	if (strcmp(CMD_NAME, "interface_list") == 0 && CMD_ARGC > 0)
+	if (strcmp(CMD_NAME, "list") == 0 && CMD_ARGC > 0)
 		return ERROR_COMMAND_SYNTAX_ERROR;
 
-	command_print(CMD, "The following debug interfaces are available:");
+	command_print(CMD, "The following debug adapters are available:");
 	for (unsigned i = 0; NULL != adapter_drivers[i]; i++) {
 		const char *name = adapter_drivers[i]->name;
 		command_print(CMD, "%u: %s", i + 1, name);
@@ -99,7 +99,7 @@ COMMAND_HANDLER(handle_interface_list_command)
 	return ERROR_OK;
 }
 
-COMMAND_HANDLER(handle_interface_command)
+COMMAND_HANDLER(handle_adapter_driver_command)
 {
 	int retval;
 
@@ -134,7 +134,7 @@ COMMAND_HANDLER(handle_interface_command)
 	 */
 	LOG_ERROR("The specified debug interface was not found (%s)",
 				CMD_ARGV[0]);
-	CALL_COMMAND_HANDLER(handle_interface_list_command);
+	CALL_COMMAND_HANDLER(handle_adapter_list_command);
 	return ERROR_JTAG_INVALID_INTERFACE;
 }
 
@@ -355,7 +355,7 @@ next:
 	return ERROR_OK;
 }
 
-COMMAND_HANDLER(handle_adapter_nsrst_delay_command)
+COMMAND_HANDLER(handle_adapter_srst_delay_command)
 {
 	if (CMD_ARGC > 1)
 		return ERROR_COMMAND_SYNTAX_ERROR;
@@ -365,11 +365,11 @@ COMMAND_HANDLER(handle_adapter_nsrst_delay_command)
 
 		jtag_set_nsrst_delay(delay);
 	}
-	command_print(CMD, "adapter_nsrst_delay: %u", jtag_get_nsrst_delay());
+	command_print(CMD, "adapter srst delay: %u", jtag_get_nsrst_delay());
 	return ERROR_OK;
 }
 
-COMMAND_HANDLER(handle_adapter_nsrst_assert_width_command)
+COMMAND_HANDLER(handle_adapter_srst_pulse_width_command)
 {
 	if (CMD_ARGC > 1)
 		return ERROR_COMMAND_SYNTAX_ERROR;
@@ -379,11 +379,11 @@ COMMAND_HANDLER(handle_adapter_nsrst_assert_width_command)
 
 		jtag_set_nsrst_assert_width(width);
 	}
-	command_print(CMD, "adapter_nsrst_assert_width: %u", jtag_get_nsrst_assert_width());
+	command_print(CMD, "adapter srst pulse_width: %u", jtag_get_nsrst_assert_width());
 	return ERROR_OK;
 }
 
-COMMAND_HANDLER(handle_adapter_khz_command)
+COMMAND_HANDLER(handle_adapter_speed_command)
 {
 	if (CMD_ARGC > 1)
 		return ERROR_COMMAND_SYNTAX_ERROR;
@@ -524,7 +524,70 @@ static const struct command_registration adapter_usb_command_handlers[] = {
 };
 #endif /* MINIDRIVER */
 
+static const struct command_registration adapter_srst_command_handlers[] = {
+	{
+		.name = "delay",
+		.handler = handle_adapter_srst_delay_command,
+		.mode = COMMAND_ANY,
+		.help = "delay after deasserting SRST in ms",
+		.usage = "[milliseconds]",
+	},
+	{
+		.name = "pulse_width",
+		.handler = handle_adapter_srst_pulse_width_command,
+		.mode = COMMAND_ANY,
+		.help = "SRST assertion pulse width in ms",
+		.usage = "[milliseconds]",
+	},
+	COMMAND_REGISTRATION_DONE
+};
+
 static const struct command_registration adapter_command_handlers[] = {
+	{
+		.name = "driver",
+		.handler = handle_adapter_driver_command,
+		.mode = COMMAND_CONFIG,
+		.help = "Select a debug adapter driver",
+		.usage = "driver_name",
+	},
+	{
+		.name = "speed",
+		.handler = handle_adapter_speed_command,
+		.mode = COMMAND_ANY,
+		.help = "With an argument, change to the specified maximum "
+			"jtag speed.  For JTAG, 0 KHz signifies adaptive "
+			"clocking. "
+			"With or without argument, display current setting.",
+		.usage = "[khz]",
+	},
+	{
+		.name = "list",
+		.handler = handle_adapter_list_command,
+		.mode = COMMAND_ANY,
+		.help = "List all built-in debug adapter drivers",
+		.usage = "",
+	},
+	{
+		.name = "name",
+		.mode = COMMAND_ANY,
+		.jim_handler = jim_adapter_name,
+		.help = "Returns the name of the currently "
+			"selected adapter (driver)",
+	},
+	{
+		.name = "srst",
+		.mode = COMMAND_ANY,
+		.help = "srst adapter command group",
+		.usage = "",
+		.chain = adapter_srst_command_handlers,
+	},
+	{
+		.name = "transports",
+		.handler = adapter_transports_command,
+		.mode = COMMAND_CONFIG,
+		.help = "Declare transports the adapter supports.",
+		.usage = "transport ... ",
+	},
 #ifndef HAVE_JTAG_MINIDRIVER_H
 	{
 		.name = "usb",
@@ -559,58 +622,6 @@ static const struct command_registration interface_command_handlers[] = {
 		.usage = "",
 		.chain = adapter_command_handlers,
 	},
-	{
-		.name = "adapter_khz",
-		.handler = handle_adapter_khz_command,
-		.mode = COMMAND_ANY,
-		.help = "With an argument, change to the specified maximum "
-			"jtag speed.  For JTAG, 0 KHz signifies adaptive "
-			" clocking. "
-			"With or without argument, display current setting.",
-		.usage = "[khz]",
-	},
-	{
-		.name = "adapter_name",
-		.mode = COMMAND_ANY,
-		.jim_handler = jim_adapter_name,
-		.help = "Returns the name of the currently "
-			"selected adapter (driver)",
-	},
-	{
-		.name = "adapter_nsrst_delay",
-		.handler = handle_adapter_nsrst_delay_command,
-		.mode = COMMAND_ANY,
-		.help = "delay after deasserting SRST in ms",
-		.usage = "[milliseconds]",
-	},
-	{
-		.name = "adapter_nsrst_assert_width",
-		.handler = handle_adapter_nsrst_assert_width_command,
-		.mode = COMMAND_ANY,
-		.help = "delay after asserting SRST in ms",
-		.usage = "[milliseconds]",
-	},
-	{
-		.name = "interface",
-		.handler = handle_interface_command,
-		.mode = COMMAND_CONFIG,
-		.help = "Select a debug adapter interface (driver)",
-		.usage = "driver_name",
-	},
-	{
-		.name = "interface_transports",
-		.handler = interface_transport_command,
-		.mode = COMMAND_CONFIG,
-		.help = "Declare transports the interface supports.",
-		.usage = "transport ... ",
-	},
-	{
-		.name = "interface_list",
-		.handler = handle_interface_list_command,
-		.mode = COMMAND_ANY,
-		.help = "List all built-in debug adapter interfaces (drivers)",
-		.usage = "",
-	},
 	{
 		.name = "reset_config",
 		.handler = handle_reset_config_command,

src/jtag/startup.tcl

@@ -120,18 +120,18 @@ proc jtag_ntrst_assert_width args {
 # FIXME phase these aids out after about April 2011
 #
 proc jtag_khz args {
-	echo "DEPRECATED! use 'adapter_khz' not 'jtag_khz'"
+	echo "DEPRECATED! use 'adapter speed' not 'jtag_khz'"
-	eval adapter_khz $args
+	eval adapter speed $args
 }
 
 proc jtag_nsrst_delay args {
-	echo "DEPRECATED! use 'adapter_nsrst_delay' not 'jtag_nsrst_delay'"
+	echo "DEPRECATED! use 'adapter srst delay' not 'jtag_nsrst_delay'"
-	eval adapter_nsrst_delay $args
+	eval adapter srst delay $args
 }
 
 proc jtag_nsrst_assert_width args {
-	echo "DEPRECATED! use 'adapter_nsrst_assert_width' not 'jtag_nsrst_assert_width'"
+	echo "DEPRECATED! use 'adapter srst pulse_width' not 'jtag_nsrst_assert_width'"
-	eval adapter_nsrst_assert_width $args
+	eval adapter srst pulse_width $args
 }
 
 proc jtag_reset args {
@@ -176,4 +176,39 @@ proc stlink args {
 	eval hla $args
 }
 
+proc adapter_khz args {
+	echo "DEPRECATED! use 'adapter speed' not 'adapter_khz'"
+	eval adapter speed $args
+}
+
+proc adapter_name args {
+	echo "DEPRECATED! use 'adapter name' not 'adapter_name'"
+	eval adapter name $args
+}
+
+proc adapter_nsrst_delay args {
+	echo "DEPRECATED! use 'adapter srst delay' not 'adapter_nsrst_delay'"
+	eval adapter srst delay $args
+}
+
+proc adapter_nsrst_assert_width args {
+	echo "DEPRECATED! use 'adapter srst pulse_width' not 'adapter_nsrst_assert_width'"
+	eval adapter srst pulse_width $args
+}
+
+proc interface args {
+	echo "DEPRECATED! use 'adapter driver' not 'interface'"
+	eval adapter driver $args
+}
+
+proc  interface_transports args {
+	echo "DEPRECATED! use 'adapter transports' not 'interface_transports'"
+	eval adapter transports $args
+}
+
+proc  interface_list args {
+	echo "DEPRECATED! use 'adapter list' not 'interface_list'"
+	eval adapter list $args
+}
+
 # END MIGRATION AIDS