[efi] Add a USB host controller driver based on EFI_USB_IO_PROTOCOL

Allow iPXE to coexist with other USB device drivers, by attaching to
the EFI_USB_IO_PROTOCOL instances provided by the UEFI platform
firmware.

The EFI_USB_IO_PROTOCOL is an unsurprisingly badly designed
abstraction of a USB device.  The poor design choices intrinsic in the
UEFI specification prevent efficient operation as a network device,
with the result that devices operated using the EFI_USB_IO_PROTOCOL
operate approximately two orders of magnitude slower than devices
operated using our native EHCI or xHCI host controller drivers.

Since the performance is so abysmally slow, and since the underlying
problems are due to fundamental architectural mistakes in the UEFI
specification, support for the EFI_USB_IO_PROTOCOL host controller
driver is left as disabled by default.  Users are advised to use the
native iPXE host controller drivers instead.

Signed-off-by: Michael Brown <mcb30@ipxe.org>

src/config/config_usb.c

@@ -43,6 +43,9 @@ REQUIRE_OBJECT ( ehci );
 #ifdef USB_HCD_UHCI
 REQUIRE_OBJECT ( uhci );
 #endif
+#ifdef USB_HCD_USBIO
+REQUIRE_OBJECT ( usbio );
+#endif
 
 /*
  * Drag in USB peripherals

src/config/usb.h

@@ -18,6 +18,7 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 //#undef	USB_HCD_XHCI		/* xHCI USB host controller */
 //#undef	USB_HCD_EHCI		/* EHCI USB host controller */
 //#undef	USB_HCD_UHCI		/* UHCI USB host controller */
+//#define	USB_HCD_USBIO		/* Very slow EFI USB host controller */
 
 /*
  * USB peripherals

src/drivers/usb/usbio.h

@@ -0,0 +1,153 @@
+#ifndef _USBIO_H
+#define _USBIO_H
+
+/** @file
+ *
+ * EFI_USB_IO_PROTOCOL pseudo Host Controller Interface driver
+ *
+ */
+
+FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
+
+#include <ipxe/list.h>
+#include <ipxe/device.h>
+#include <ipxe/efi/efi.h>
+#include <ipxe/efi/Protocol/UsbIo.h>
+#include <ipxe/efi/Protocol/DevicePath.h>
+#include <ipxe/usb.h>
+
+/** USB I/O maximum transfer size
+ *
+ * The API provides no way to discover the maximum transfer size.
+ * Assume the 16kB supported by EHCI.
+ */
+#define USBIO_MTU 16384
+
+/** USB I/O interrupt ring buffer size
+ *
+ * This is a policy decision.
+ */
+#define USBIO_INTR_COUNT 4
+
+/** A USB interrupt ring buffer */
+struct usbio_interrupt_ring {
+	/** USB I/O endpoint */
+	struct usbio_endpoint *endpoint;
+	/** Producer counter */
+	unsigned int prod;
+	/** Consumer counter */
+	unsigned int cons;
+	/** Data buffers */
+	void *data[USBIO_INTR_COUNT];
+	/** Lengths */
+	size_t len[USBIO_INTR_COUNT];
+};
+
+/** USB I/O ring buffer size
+ *
+ * This is a policy decision.
+ */
+#define USBIO_RING_COUNT 64
+
+/** A USB I/O endpoint */
+struct usbio_endpoint {
+	/** USB I/O device */
+	struct usbio_device *usbio;
+	/** USB endpoint */
+	struct usb_endpoint *ep;
+	/** List of endpoints */
+	struct list_head list;
+	/** USB I/O endpoint operations */
+	struct usbio_operations *op;
+
+	/** Containing interface number */
+	unsigned int interface;
+	/** EFI handle */
+	EFI_HANDLE handle;
+	/** USB I/O protocol */
+	EFI_USB_IO_PROTOCOL *io;
+
+	/** Producer counter */
+	unsigned int prod;
+	/** Consumer counter */
+	unsigned int cons;
+	/** I/O buffers */
+	struct io_buffer *iobuf[USBIO_RING_COUNT];
+	/** Flags */
+	uint8_t flags[USBIO_RING_COUNT];
+
+	/** Interrupt ring buffer (if applicable) */
+	struct usbio_interrupt_ring *intr;
+};
+
+/** USB I/O transfer flags */
+enum usbio_flags {
+	/** This is a message transfer */
+	USBIO_MESSAGE = 0x01,
+	/** This transfer requires zero-length packet termination */
+	USBIO_ZLEN = 0x02,
+};
+
+/** USB I/O endpoint operations */
+struct usbio_operations {
+	/** Open endpoint
+	 *
+	 * @v endpoint		Endpoint
+	 * @ret rc		Return status code
+	 */
+	int ( * open ) ( struct usbio_endpoint *endpoint );
+	/** Close endpoint
+	 *
+	 * @v endpoint		Endpoint
+	 */
+	void ( * close ) ( struct usbio_endpoint *endpoint );
+	/** Poll endpoint
+	 *
+	 * @v endpoint		Endpoint
+	 */
+	void ( * poll ) ( struct usbio_endpoint *endpoint );
+};
+
+/** A USB I/O protocol interface */
+struct usbio_interface {
+	/** EFI device handle */
+	EFI_HANDLE handle;
+	/** USB I/O protocol */
+	EFI_USB_IO_PROTOCOL *io;
+	/** Usage count */
+	unsigned int count;
+};
+
+/** A USB I/O protocol device
+ *
+ * We model each externally-provided USB I/O protocol device as a host
+ * controller containing a root hub with a single port.
+ */
+struct usbio_device {
+	/** EFI device handle */
+	EFI_HANDLE handle;
+	/** USB I/O protocol */
+	EFI_USB_IO_PROTOCOL *io;
+	/** Generic device */
+	struct device dev;
+
+	/** Configuration descriptor */
+	struct usb_configuration_descriptor *config;
+
+	/** Device path */
+	EFI_DEVICE_PATH_PROTOCOL *path;
+	/** Final component of USB device path */
+	USB_DEVICE_PATH *usbpath;
+
+	/** First interface number */
+	uint8_t first;
+	/** USB I/O protocol interfaces */
+	struct usbio_interface *interface;
+
+	/** USB bus */
+	struct usb_bus *bus;
+	/** List of endpoints */
+	struct list_head endpoints;
+};
+
+#endif /* _USBIO_H */

src/include/ipxe/errfile.h

@@ -85,6 +85,7 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 #define ERRFILE_uhci		     ( ERRFILE_DRIVER | 0x000b0000 )
 #define ERRFILE_usbhid		     ( ERRFILE_DRIVER | 0x000c0000 )
 #define ERRFILE_usbkbd		     ( ERRFILE_DRIVER | 0x000d0000 )
+#define ERRFILE_usbio		     ( ERRFILE_DRIVER | 0x000e0000 )
 
 #define ERRFILE_nvs		     ( ERRFILE_DRIVER | 0x00100000 )
 #define ERRFILE_spi		     ( ERRFILE_DRIVER | 0x00110000 )

src/include/ipxe/usb.h

@@ -68,7 +68,7 @@ enum usb_pid {
 struct usb_setup_packet {
 	/** Request */
 	uint16_t request;
-	/** Value paramer */
+	/** Value parameter */
 	uint16_t value;
 	/** Index parameter */
 	uint16_t index;
@@ -91,6 +91,9 @@ struct usb_setup_packet {
 /** Vendor-specific request type */
 #define USB_TYPE_VENDOR ( 2 << 5 )
 
+/** Request recipient mask */
+#define USB_RECIP_MASK ( 0x1f << 0 )
+
 /** Request recipient is the device */
 #define USB_RECIP_DEVICE ( 0 << 0 )