raiden_debug: Upstream ChromiumOS usb_device helpers

These are helpful usb device accessors and helpers that
are later used for the so-called Raiden debugger programmer.

BUG=b:143389556
BRANCH=none
TEST=builds

Change-Id: Ic928220fc919fe4958c8150e61e11470dac88f13
Signed-off-by: Edward O'Callaghan <quasisec@google.com>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/38936
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>

Makefile

@@ -1088,7 +1088,7 @@ endif
 ifneq ($(NEED_LIBUSB1), )
 CHECK_LIBUSB1 = yes
 FEATURE_CFLAGS += -D'NEED_LIBUSB1=1'
-PROGRAMMER_OBJS += usbdev.o
+PROGRAMMER_OBJS += usbdev.o usb_device.o
 # FreeBSD and DragonflyBSD use a reimplementation of libusb-1.0 that is simply called libusb
 ifeq ($(TARGET_OS),$(filter $(TARGET_OS),FreeBSD DragonFlyBSD))
 USB1LIBS += -lusb

meson.build

@@ -84,6 +84,7 @@ endif
 # some programmers require libusb
 if get_option('usb')
   srcs += 'usbdev.c'
+  srcs += 'usb_device.c'
   deps += dependency('libusb-1.0')
 else
   config_ch341a_spi = false

usb_device.c

@@ -0,0 +1,393 @@
+/*
+ * This file is part of the flashrom project.
+ *
+ * Copyright (C) 2020, Google Inc. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#include "programmer.h"
+#include "spi.h"
+#include "usb_device.h"
+
+#include <assert.h>
+#include <libusb.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/*
+ * Possibly extract a programmer parameter and use it to initialize the given
+ * match value structure.
+ */
+static void usb_match_value_init(struct usb_match_value *match,
+				 char const *parameter)
+{
+	char *string = extract_programmer_param(parameter);
+
+	match->name = parameter;
+
+	if (string) {
+		match->set = 1;
+		match->value = strtol(string, NULL, 0);
+	} else {
+		match->set = 0;
+	}
+
+	free(string);
+}
+
+#define USB_MATCH_VALUE_INIT(NAME)			\
+	usb_match_value_init(&match->NAME, #NAME)
+
+void usb_match_init(struct usb_match *match)
+{
+	USB_MATCH_VALUE_INIT(vid);
+	USB_MATCH_VALUE_INIT(pid);
+	USB_MATCH_VALUE_INIT(bus);
+	USB_MATCH_VALUE_INIT(address);
+	USB_MATCH_VALUE_INIT(config);
+	USB_MATCH_VALUE_INIT(interface);
+	USB_MATCH_VALUE_INIT(altsetting);
+	USB_MATCH_VALUE_INIT(class);
+	USB_MATCH_VALUE_INIT(subclass);
+	USB_MATCH_VALUE_INIT(protocol);
+}
+
+void usb_match_value_default(struct usb_match_value *value,
+			     long int default_value)
+{
+	if (value->set)
+		return;
+
+	value->set   = 1;
+	value->value = default_value;
+}
+
+/*
+ * Match the value against a possible user supplied parameter.
+ *
+ * Return:
+ *     0: The user supplied the given parameter and it did not match the value.
+ *     1: Either the user didn't supply the parameter, or they did and it
+ *        matches the given value.
+ */
+static int check_match(struct usb_match_value const *match_value, int value)
+{
+	int reject = match_value->set && (match_value->value != value);
+
+	if (reject)
+		msg_pdbg("USB: Rejecting device because %s = %d != %d\n",
+			 match_value->name,
+			 value,
+			 match_value->value);
+
+	return !reject;
+}
+
+/*
+ * Allocate a copy of device and add it to the head of the devices list.
+ */
+static void add_device(struct usb_device *device,
+		       struct usb_device **devices)
+{
+	struct usb_device *copy = malloc(sizeof(struct usb_device));
+
+	assert(copy != NULL);
+
+	*copy = *device;
+
+	copy->next = *devices;
+	*devices = copy;
+
+	libusb_ref_device(copy->device);
+}
+
+/*
+ * Look through the interfaces of the current device config for a match. Stop
+ * looking after the first valid match is found.
+ *
+ * Return:
+ *     0: No matching interface was found.
+ *     1: A complete match was found and added to the devices list.
+ */
+static int find_interface(struct usb_match const *match,
+			  struct usb_device *current,
+			  struct usb_device **devices)
+{
+	int i, j;
+
+	for (i = 0; i < current->config_descriptor->bNumInterfaces; ++i) {
+		struct libusb_interface const *interface;
+
+		interface = &current->config_descriptor->interface[i];
+
+		for (j = 0; j < interface->num_altsetting; ++j) {
+			struct libusb_interface_descriptor const *descriptor;
+
+			descriptor = &interface->altsetting[j];
+
+			if (check_match(&match->interface,
+					descriptor->bInterfaceNumber) &&
+			    check_match(&match->altsetting,
+					descriptor->bAlternateSetting) &&
+			    check_match(&match->class,
+					descriptor->bInterfaceClass) &&
+			    check_match(&match->subclass,
+					descriptor->bInterfaceSubClass) &&
+			    check_match(&match->protocol,
+					descriptor->bInterfaceProtocol)) {
+				current->interface_descriptor = descriptor;
+				add_device(current, devices);
+				msg_pdbg("USB: Found matching device\n");
+				return 1;
+			}
+		}
+	}
+
+	return 0;
+}
+
+/*
+ * Look through the configs of the current device for a match.  Stop looking
+ * after the first valid match is found.
+ *
+ * Return:
+ *     0: All configurations successfully checked, one may have been added to
+ *        the list.
+ *     non-zero: There was a failure while checking for a match.
+ */
+static int find_config(struct usb_match const *match,
+		       struct usb_device *current,
+		       struct libusb_device_descriptor const *device_descriptor,
+		       struct usb_device **devices)
+{
+	int i;
+
+	for (i = 0; i < device_descriptor->bNumConfigurations; ++i) {
+		int ret = LIBUSB(libusb_get_config_descriptor(
+				current->device, i,
+				&current->config_descriptor));
+		if (ret != 0) {
+			msg_perr("USB: Failed to get config descriptor");
+			return ret;
+		}
+
+		if (check_match(&match->config,
+				current->config_descriptor->
+				bConfigurationValue) &&
+		    find_interface(match, current, devices))
+			break;
+
+		libusb_free_config_descriptor(current->config_descriptor);
+	}
+
+	return 0;
+}
+
+int usb_device_find(struct usb_match const *match, struct usb_device **devices)
+{
+	libusb_device **list;
+	ssize_t         count;
+	ssize_t         i;
+
+	*devices = NULL;
+
+	int ret = LIBUSB(count = libusb_get_device_list(NULL, &list));
+	if (ret != 0) {
+		msg_perr("USB: Failed to get device list");
+		return ret;
+	}
+
+	for (i = 0; i < count; ++i) {
+		struct libusb_device_descriptor descriptor;
+		struct usb_device               current = {
+			.device = list[i],
+			.handle = NULL,
+			.next   = NULL,
+		};
+
+		uint8_t bus     = libusb_get_bus_number(list[i]);
+		uint8_t address = libusb_get_device_address(list[i]);
+
+		msg_pdbg("USB: Inspecting device (Bus %d, Address %d)\n",
+			 bus,
+			 address);
+
+		ret = LIBUSB(libusb_get_device_descriptor(list[i],
+							  &descriptor));
+		      if (ret != 0) {
+			      msg_perr("USB: Failed to get device descriptor");
+			      return ret;
+		      }
+
+		if (check_match(&match->vid,     descriptor.idVendor) &&
+		    check_match(&match->pid,     descriptor.idProduct) &&
+		    check_match(&match->bus,     bus) &&
+		    check_match(&match->address, address)) {
+			ret = find_config(match,
+					  &current,
+					  &descriptor,
+					  devices);
+			if (ret != 0) {
+				msg_perr("USB: Failed to find config");
+				return ret;
+			}
+		}
+	}
+
+	libusb_free_device_list(list, 1);
+
+	return (*devices == NULL);
+}
+
+/*
+ * If the underlying libusb device is not open, open it.
+ *
+ * Return:
+ *     0: The device was already open or was successfully opened.
+ *     non-zero: There was a failure while opening the device.
+ */
+static int usb_device_open(struct usb_device *device)
+{
+	if (device->handle == NULL) {
+		int ret = LIBUSB(libusb_open(device->device, &device->handle));
+		if (ret != 0) {
+			msg_perr("USB: Failed to open device\n");
+			return ret;
+		}
+	}
+
+	return 0;
+}
+
+int usb_device_show(char const *prefix, struct usb_device *device)
+{
+	struct libusb_device_descriptor descriptor;
+	unsigned char                   product[256];
+	int ret;
+
+	ret = usb_device_open(device);
+	if (ret != 0) {
+	       msg_perr("USB: Failed to open device\n");
+	       return ret;
+	}
+
+	ret = LIBUSB(libusb_get_device_descriptor(device->device, &descriptor));
+	if (ret != 0) {
+		msg_perr("USB: Failed to get device descriptor\n");
+		return ret;
+	}
+
+	ret = LIBUSB(libusb_get_string_descriptor_ascii(
+			     device->handle,
+			     descriptor.iProduct,
+			     product,
+			     sizeof(product)));
+	if (ret != 0) {
+		msg_perr("USB: Failed to get device product string\n");
+		return ret;
+	}
+
+	product[255] = '\0';
+
+	msg_perr("%sbus=0x%02x,address=0x%02x | %s\n",
+		 prefix,
+		 libusb_get_bus_number(device->device),
+		 libusb_get_device_address(device->device),
+		 product);
+
+	return 0;
+}
+
+int usb_device_claim(struct usb_device *device)
+{
+	int current_config;
+
+	int ret = usb_device_open(device);
+	if (ret != 0) {
+		msg_perr("USB: Failed to open device\n");
+		return ret;
+	}
+
+	ret = LIBUSB(libusb_get_configuration(device->handle,
+					      &current_config));
+	if (ret != 0) {
+		msg_perr("USB: Failed to get current device configuration\n");
+		return ret;
+	}
+
+	if (current_config != device->config_descriptor->bConfigurationValue) {
+		ret = LIBUSB(libusb_set_configuration(
+				     device->handle,
+				     device->
+				     config_descriptor->
+				     bConfigurationValue));
+		if (ret != 0) {
+			msg_perr("USB: Failed to set new configuration from %d to %d\n",
+					current_config,
+					device->config_descriptor->bConfigurationValue);
+			return ret;
+		}
+	}
+
+	ret = LIBUSB(libusb_set_auto_detach_kernel_driver(device->handle, 1));
+	if (ret != 0) {
+		msg_perr("USB: Failed to enable auto kernel driver detach\n");
+		return ret;
+	}
+
+	ret = LIBUSB(libusb_claim_interface(device->handle,
+					    device->
+					    interface_descriptor->
+					    bInterfaceNumber));
+	if (ret != 0) {
+		msg_perr("USB: Could not claim device interface %d\n",
+				device->interface_descriptor->bInterfaceNumber);
+		return ret;
+	}
+
+	if (device->interface_descriptor->bAlternateSetting != 0) {
+		ret = LIBUSB(libusb_set_interface_alt_setting(
+				     device->handle,
+				     device->
+				     interface_descriptor->
+				     bInterfaceNumber,
+				     device->
+				     interface_descriptor->
+				     bAlternateSetting));
+		if (ret != 0) {
+			msg_perr("USB: Failed to set alternate setting %d\n",
+					device->interface_descriptor->bAlternateSetting);
+			return ret;
+		}
+	}
+
+	return 0;
+}
+
+struct usb_device *usb_device_free(struct usb_device *device)
+{
+	struct usb_device *next = device->next;
+
+	if (device->handle != NULL)
+		libusb_close(device->handle);
+
+	/*
+	 * This unref balances the ref added in the add_device function.
+	 */
+	libusb_unref_device(device->device);
+	libusb_free_config_descriptor(device->config_descriptor);
+
+	free(device);
+
+	return next;
+}

usb_device.h

@@ -0,0 +1,164 @@
+/*
+ * This file is part of the flashrom project.
+ *
+ * Copyright (C) 2020, Google Inc. All rights reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#ifndef USB_DEVICE_H
+#define USB_DEVICE_H
+
+/*
+ * USB device matching framework
+ *
+ * This can be used to match a USB device by a number of different parameters.
+ * The parameters can be passed on the command line and defaults can be set
+ * by the programmer.
+ */
+
+#include <libusb.h>
+#include <stdint.h>
+
+/*
+ * The LIBUSB macro converts a libusb failure code into an error code that
+ * flashrom recognizes.  It also displays additional libusb specific
+ * information about the failure.
+ */
+#define LIBUSB(expression)				      		\
+	({						      		\
+		int libusb_error__ = (expression);		      	\
+									\
+		if (libusb_error__ < 0) {			      	\
+			msg_perr("libusb error: %s:%d %s\n",  		\
+				 __FILE__,		      		\
+				 __LINE__,		      		\
+				 libusb_error_name(libusb_error__)); 	\
+			libusb_error__ = 0x20000 | -libusb_error__;	\
+		} else {				      		\
+			libusb_error__ = 0;			      	\
+		}					      		\
+									\
+		libusb_error__;				      		\
+	})
+
+/*
+ * A USB match and associated value struct are used to encode the information
+ * about a device against which we wish to match.  If the value of a
+ * usb_match_value has been set then a device must match that value.  The name
+ * of the usb_match_value is used to fetch the programmer parameter from the
+ * flashrom command line and is the same as the name of the corresponding
+ * field in usb_match.
+ */
+struct usb_match_value {
+	char const *name;
+	int         value;
+	int         set;
+};
+
+struct usb_match {
+	struct usb_match_value bus;
+	struct usb_match_value address;
+	struct usb_match_value vid;
+	struct usb_match_value pid;
+	struct usb_match_value serial;
+	struct usb_match_value config;
+	struct usb_match_value interface;
+	struct usb_match_value altsetting;
+	struct usb_match_value class;
+	struct usb_match_value subclass;
+	struct usb_match_value protocol;
+};
+
+/*
+ * Initialize a usb_match structure so that each value's name matches the
+ * values name in the usb_match structure (so bus.name == "bus"...), and
+ * look for each value in the flashrom command line via
+ * extract_programmer_param.  If the value is found convert it to an integer
+ * using strtol, accepting hex, decimal and octal encoding.
+ */
+void usb_match_init(struct usb_match *match);
+
+/*
+ * Add a default value to a usb_match_value.  This must be done after calling
+ * usb_match_init.  If usb_match_init already set the value of a usb_match_value
+ * we do nothing, otherwise set the value to default_value.  This ensures that
+ * parameters passed on the command line override defaults.
+ */
+void usb_match_value_default(struct usb_match_value *match,
+			     long int default_value);
+
+/*
+ * The usb_device structure is an entry in a linked list of devices that were
+ * matched by usb_device_find.
+ */
+struct usb_device {
+	struct libusb_device                     *device;
+	struct libusb_config_descriptor          *config_descriptor;
+	struct libusb_interface_descriptor const *interface_descriptor;
+
+	/*
+	 * Initially NULL, the libusb_device_handle is only valid once the
+	 * usb_device has been successfully passed to usb_device_show or
+	 * usb_device_claim.
+	 */
+	struct libusb_device_handle *handle;
+
+	/*
+	 * Link to next device, or NULL
+	 */
+	struct usb_device *next;
+};
+
+/*
+ * Find and return a list of all compatible devices.  Each device is added to
+ * the list with its first valid configuration and interface.  If an alternate
+ * configuration (config, interface, altsetting...) is desired the specifics
+ * can be supplied as programmer parameters.
+ *
+ * Return:
+ *     0: At least one matching device was found.
+ *     1: No matching devices were found.
+ */
+int usb_device_find(struct usb_match const *match, struct usb_device **devices);
+
+/*
+ * Display the devices bus and address as well as its product string.  The
+ * underlying libusb device is opened if it is not already open.
+ *
+ * Return:
+ *     0: The device information was displayed.
+ *     non-zero: There was a failure while displaying the device information.
+ */
+int usb_device_show(char const *prefix, struct usb_device *device);
+
+/*
+ * Open the underlying libusb device, set its config, claim the interface and
+ * select the correct alternate interface.
+ *
+ * Return:
+ *     0: The device was successfully claimed.
+ *     non-zero: There was a failure while trying to claim the device.
+ */
+int usb_device_claim(struct usb_device *device);
+
+/*
+ * Free a usb_device structure.
+ *
+ * This ensures that the libusb device is closed and that all allocated
+ * handles and descriptors are freed.
+ *
+ * Return:
+ *     The next device in the device list.
+ */
+struct usb_device *usb_device_free(struct usb_device *device);
+
+#endif /* USB_DEVICE_H */