drivers: call adapter_get_required_serial() in jtag_libusb_open()

Now that adapter serial is handled independently from the adapter
drivers, move inside jtag_libusb_open() the call to
adapter_get_required_serial(), so every adapter that uses libusb
will automagically get USB serial support.

Extend the documentation to list the adapters involved.

Change-Id: I75b3482d38f8ed3418329f3106c5e8b689fd460b
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6663
Tested-by: jenkins

doc/openocd.texi

@@ -2371,7 +2371,8 @@ This command is only available if your libusb1 is at least version 1.0.16.
 Specifies the @var{serial_string} of the adapter to use.
 If this command is not specified, serial strings are not checked.
 Only the following adapter drivers use the serial string from this command:
-cmsis_dap, ft232r, ftdi, hla, jlink, kitprog, presto, st-link, vsllink, xds110.
+aice (aice_usb), arm-jtag-ew, cmsis_dap, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus,
+openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
 @end deffn
 
 @section Interface Drivers

src/jtag/aice/aice_usb.c

@@ -2085,7 +2085,7 @@ static int aice_usb_open(struct aice_port_param_s *param)
 	const uint16_t pids[] = { param->pid, 0 };
 	struct libusb_device_handle *devh;
 
-	if (jtag_libusb_open(vids, pids, NULL, &devh, NULL) != ERROR_OK)
+	if (jtag_libusb_open(vids, pids, &devh, NULL) != ERROR_OK)
 		return ERROR_FAIL;
 
 	/* BE ***VERY CAREFUL*** ABOUT MAKING CHANGES IN THIS
@@ -2109,7 +2109,7 @@ static int aice_usb_open(struct aice_port_param_s *param)
 	/* reopen jlink after usb_reset
 	 * on win32 this may take a second or two to re-enumerate */
 	int retval;
-	while ((retval = jtag_libusb_open(vids, pids, NULL, &devh, NULL)) != ERROR_OK) {
+	while ((retval = jtag_libusb_open(vids, pids, &devh, NULL)) != ERROR_OK) {
 		usleep(1000);
 		timeout--;
 		if (!timeout)

src/jtag/drivers/arm-jtag-ew.c

@@ -688,7 +688,7 @@ static struct armjtagew *armjtagew_usb_open(void)
 	const uint16_t pids[] = { USB_PID, 0 };
 	struct libusb_device_handle *dev;
 
-	if (jtag_libusb_open(vids, pids, NULL, &dev, NULL) != ERROR_OK)
+	if (jtag_libusb_open(vids, pids, &dev, NULL) != ERROR_OK)
 		return NULL;
 
 	struct armjtagew *result = malloc(sizeof(struct armjtagew));

src/jtag/drivers/ft232r.c

@@ -257,8 +257,8 @@ static int ft232r_init(void)
 {
 	uint16_t avids[] = {ft232r_vid, 0};
 	uint16_t apids[] = {ft232r_pid, 0};
-	const char *ft232r_serial_desc = adapter_get_required_serial();
+	if (jtag_libusb_open(avids, apids, &adapter, NULL)) {
-	if (jtag_libusb_open(avids, apids, ft232r_serial_desc, &adapter, NULL)) {
+		const char *ft232r_serial_desc = adapter_get_required_serial();
 		LOG_ERROR("ft232r not found: vid=%04x, pid=%04x, serial=%s\n",
 			ft232r_vid, ft232r_pid, (!ft232r_serial_desc) ? "[any]" : ft232r_serial_desc);
 		return ERROR_JTAG_INIT_FAILED;

src/jtag/drivers/kitprog.c

@@ -39,7 +39,6 @@
 
 #include <hidapi.h>
 
-#include <jtag/adapter.h>
 #include <jtag/interface.h>
 #include <jtag/swd.h>
 #include <jtag/commands.h>
@@ -271,8 +270,7 @@ static int kitprog_usb_open(void)
 	const uint16_t vids[] = { VID, 0 };
 	const uint16_t pids[] = { PID, 0 };
 
-	if (jtag_libusb_open(vids, pids, adapter_get_required_serial(),
+	if (jtag_libusb_open(vids, pids, &kitprog_handle->usb_handle, NULL) != ERROR_OK) {
-			&kitprog_handle->usb_handle, NULL) != ERROR_OK) {
 		LOG_ERROR("Failed to open or find the device");
 		return ERROR_FAIL;
 	}

src/jtag/drivers/libusb_helper.c

@@ -157,7 +157,6 @@ static bool jtag_libusb_match_serial(struct libusb_device_handle *device,
 }
 
 int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[],
-		const char *serial,
 		struct libusb_device_handle **out,
 		adapter_get_alternate_serial_fn adapter_get_alternate_serial)
 {
@@ -165,6 +164,7 @@ int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[],
 	int retval = ERROR_FAIL;
 	bool serial_mismatch = false;
 	struct libusb_device_handle *libusb_handle = NULL;
+	const char *serial = adapter_get_required_serial();
 
 	if (libusb_init(&jtag_libusb_context) < 0)
 		return ERROR_FAIL;

src/jtag/drivers/libusb_helper.h

@@ -28,7 +28,6 @@ typedef char * (*adapter_get_alternate_serial_fn)(struct libusb_device_handle *d
 		struct libusb_device_descriptor *dev_desc);
 
 int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[],
-		const char *serial,
 		struct libusb_device_handle **out,
 		adapter_get_alternate_serial_fn adapter_get_alternate_serial);
 void jtag_libusb_close(struct libusb_device_handle *dev);

src/jtag/drivers/opendous.c

@@ -706,7 +706,7 @@ struct opendous_jtag *opendous_usb_open(void)
 	struct opendous_jtag *result;
 
 	struct libusb_device_handle *devh;
-	if (jtag_libusb_open(opendous_probe->VID, opendous_probe->PID, NULL, &devh, NULL) != ERROR_OK)
+	if (jtag_libusb_open(opendous_probe->VID, opendous_probe->PID, &devh, NULL) != ERROR_OK)
 		return NULL;
 
 	jtag_libusb_set_configuration(devh, 0);

src/jtag/drivers/openjtag.c

@@ -449,7 +449,7 @@ static int openjtag_init_cy7c65215(void)
 	int ret;
 
 	usbh = NULL;
-	ret = jtag_libusb_open(cy7c65215_vids, cy7c65215_pids, NULL, &usbh, NULL);
+	ret = jtag_libusb_open(cy7c65215_vids, cy7c65215_pids, &usbh, NULL);
 	if (ret != ERROR_OK) {
 		LOG_ERROR("unable to open cy7c65215 device");
 		goto err;

src/jtag/drivers/osbdm.c

@@ -374,7 +374,7 @@ static int osbdm_flush(struct osbdm *osbdm, struct queue *queue)
 static int osbdm_open(struct osbdm *osbdm)
 {
 	(void)memset(osbdm, 0, sizeof(*osbdm));
-	if (jtag_libusb_open(osbdm_vid, osbdm_pid, NULL, &osbdm->devh, NULL) != ERROR_OK)
+	if (jtag_libusb_open(osbdm_vid, osbdm_pid, &osbdm->devh, NULL) != ERROR_OK)
 		return ERROR_FAIL;
 
 	if (libusb_claim_interface(osbdm->devh, 0) != ERROR_OK)

src/jtag/drivers/rlink.c

@@ -1461,7 +1461,7 @@ static int rlink_init(void)
 
 	const uint16_t vids[] = { USB_IDVENDOR, 0 };
 	const uint16_t pids[] = { USB_IDPRODUCT, 0 };
-	if (jtag_libusb_open(vids, pids, NULL, &hdev, NULL) != ERROR_OK)
+	if (jtag_libusb_open(vids, pids, &hdev, NULL) != ERROR_OK)
 		return ERROR_FAIL;
 
 	struct libusb_device_descriptor descriptor;

src/jtag/drivers/stlink_usb.c

@@ -3364,7 +3364,7 @@ static int stlink_usb_usb_open(void *handle, struct hl_interface_param_s *param)
 	  in order to become operational.
 	 */
 	do {
-		if (jtag_libusb_open(param->vid, param->pid, adapter_get_required_serial(),
+		if (jtag_libusb_open(param->vid, param->pid,
 				&h->usb_backend_priv.fd, stlink_usb_get_alternate_serial) != ERROR_OK) {
 			LOG_ERROR("open failed");
 			return ERROR_FAIL;

src/jtag/drivers/ti_icdi_usb.c

@@ -686,7 +686,7 @@ static int icdi_usb_open(struct hl_interface_param_s *param, void **fd)
 
 	/* TI (Stellaris) ICDI provides its serial number in the USB descriptor;
 	   no need to provide a callback here. */
-	jtag_libusb_open(param->vid, param->pid, adapter_get_required_serial(), &h->usb_dev, NULL);
+	jtag_libusb_open(param->vid, param->pid, &h->usb_dev, NULL);
 
 	if (!h->usb_dev) {
 		LOG_ERROR("open failed");

src/jtag/drivers/usb_blaster/ublast2_access_libusb.c

@@ -210,7 +210,7 @@ static int ublast2_libusb_init(struct ublast_lowlevel *low)
 	bool renumeration = false;
 	int ret;
 
-	if (jtag_libusb_open(vids, pids, NULL, &temp, NULL) == ERROR_OK) {
+	if (jtag_libusb_open(vids, pids, &temp, NULL) == ERROR_OK) {
 		LOG_INFO("Altera USB-Blaster II (uninitialized) found");
 		LOG_INFO("Loading firmware...");
 		ret = load_usb_blaster_firmware(temp, low);
@@ -224,15 +224,13 @@ static int ublast2_libusb_init(struct ublast_lowlevel *low)
 	const uint16_t pids_renum[] = { low->ublast_pid, 0 };
 
 	if (renumeration == false) {
-		if (jtag_libusb_open(vids_renum, pids_renum, NULL,
+		if (jtag_libusb_open(vids_renum, pids_renum, &low->libusb_dev, NULL) != ERROR_OK) {
-				&low->libusb_dev, NULL) != ERROR_OK) {
 			LOG_ERROR("Altera USB-Blaster II not found");
 			return ERROR_FAIL;
 		}
 	} else {
 		int retry = 10;
-		while (jtag_libusb_open(vids_renum, pids_renum, NULL,
+		while (jtag_libusb_open(vids_renum, pids_renum, &low->libusb_dev, NULL) != ERROR_OK && retry--) {
-				&low->libusb_dev, NULL) != ERROR_OK && retry--) {
 			usleep(1000000);
 			LOG_INFO("Waiting for reenumerate...");
 		}

src/jtag/drivers/usbprog.c

@@ -354,7 +354,7 @@ struct usbprog_jtag *usbprog_jtag_open(void)
 	const uint16_t pids[] = { PID, 0 };
 	struct libusb_device_handle *dev;
 
-	if (jtag_libusb_open(vids, pids, NULL, &dev, NULL) != ERROR_OK)
+	if (jtag_libusb_open(vids, pids, &dev, NULL) != ERROR_OK)
 		return NULL;
 
 	struct usbprog_jtag *tmp = malloc(sizeof(struct usbprog_jtag));