jtag/adapter: add command 'adapter serial'

Several adapter define their own command to specify the USB serial
number or serial string to be used during USB search.

Define a general command 'adapter serial' to be proposed as
replacement of the driver specific ones.
No driver is changed so far to use it.

Change-Id: I7631687a4163ccc63a9bdf3ad1fcb300fc483d3a
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6647
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
Tested-by: jenkins

doc/openocd.texi

@@ -2367,6 +2367,14 @@ The USB bus topology can be queried with the command @emph{lsusb -t} or @emph{dm
 This command is only available if your libusb1 is at least version 1.0.16.
 @end deffn
 
+@deffn {Config Command} {adapter serial} serial_string
+Specifies the @var{serial_string} of the adapter to use.
+If this command is not specified, serial strings are not checked.
+No adapter uses this command, so far.
+The following adapters have their own command to specify the serial string:
+cmsis_dap, ft232r, ftdi, hla, jlink, kitprog, presto, st-link, vsllink, xds110.
+@end deffn
+
 @section Interface Drivers
 
 Each of the interface drivers listed here must be explicitly

src/jtag/adapter.c

@@ -42,6 +42,7 @@ enum adapter_clk_mode {
 static struct {
 	bool adapter_initialized;
 	char *usb_location;
+	char *serial;
 	enum adapter_clk_mode clock_mode;
 	int speed_khz;
 	int rclk_fallback_speed_khz;
@@ -120,6 +121,7 @@ int adapter_quit(void)
 			LOG_ERROR("failed: %d", result);
 	}
 
+	free(adapter_config.serial);
 	free(adapter_config.usb_location);
 
 	struct jtag_tap *t = jtag_all_taps();
@@ -223,6 +225,11 @@ int adapter_get_speed_readable(int *khz)
 	return adapter_driver->speed_div(speed_var, khz);
 }
 
+const char *adapter_get_required_serial(void)
+{
+	return adapter_config.serial;
+}
+
 /*
  * 1 char: bus
  * 2 * 7 chars: max 7 ports
@@ -659,6 +666,16 @@ COMMAND_HANDLER(handle_adapter_speed_command)
 	return retval;
 }
 
+COMMAND_HANDLER(handle_adapter_serial_command)
+{
+	if (CMD_ARGC != 1)
+		return ERROR_COMMAND_SYNTAX_ERROR;
+
+	free(adapter_config.serial);
+	adapter_config.serial = strdup(CMD_ARGV[0]);
+	return ERROR_OK;
+}
+
 COMMAND_HANDLER(handle_adapter_reset_de_assert)
 {
 	enum values {
@@ -806,6 +823,13 @@ static const struct command_registration adapter_command_handlers[] = {
 			"With or without argument, display current setting.",
 		.usage = "[khz]",
 	},
+	{
+		.name = "serial",
+		.handler = handle_adapter_serial_command,
+		.mode = COMMAND_CONFIG,
+		.help = "Set the serial number of the adapter",
+		.usage = "serial_string",
+	},
 	{
 		.name = "list",
 		.handler = handle_adapter_list_command,

src/jtag/adapter.h

@@ -55,4 +55,7 @@ int adapter_config_rclk(unsigned int fallback_speed_khz);
 /** Retrieves the clock speed of the adapter in kHz. */
 unsigned int adapter_get_speed_khz(void);
 
+/** Retrieves the serial number set with command 'adapter serial' */
+const char *adapter_get_required_serial(void);
+
 #endif /* OPENOCD_JTAG_ADAPTER_H */