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>

1 files changed, 164 insertions, 0 deletions

diff --git a/usb_device.h b/usb_device.h
new file mode 100644
index 00000000..d3796757
--- /dev/null
+++ b/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 */