From 80150dc51260bec0a96fb6e7b8152abba9fc3950 Mon Sep 17 00:00:00 2001
From: David Brownell <david-b@pacbell.net>
Date: Thu, 4 Sep 2003 01:27:04 -0700
Subject: [PATCH] USB: usb "gadgetfs" (1/2)

This is another "gadget" driver -- one that lets user mode
code implement usb device functions, with all the classic
advantages of such solutions.  There's an example driver
at the linux-usb "gadget" web page, which uses pthreads
and handles several control requests in user mode.

This capability is packaged in the form of a filesystem,
conventionally mounted at /dev/gadget, with files that the
user mode driver opens, configures, and then uses with
normal read() and write() system calls.  Because this
doesn't require use of ioctl(), such user mode drivers
can be written in almost any language:  not just C, but
also Java, Python, Perl, and others -- likely even BASH.

For now, such user mode gadget drivers are limited to a
single configuration, although the interfaces in that
configuration could support multiple altsettings when
the hardware allows.

Please merge.  This first patch provides the driver,
the next one adds kconfig and kbuild support.
---
 include/linux/usb_gadgetfs.h | 75 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 include/linux/usb_gadgetfs.h

(limited to 'include/linux')

diff --git a/include/linux/usb_gadgetfs.h b/include/linux/usb_gadgetfs.h
new file mode 100644
index 000000000000..b53d6ae8e55e
--- /dev/null
+++ b/include/linux/usb_gadgetfs.h
@@ -0,0 +1,75 @@
+
+#include <asm/types.h>
+#include <asm/ioctl.h>
+
+#include <linux/usb_ch9.h>
+
+/*
+ * Filesystem based user-mode API to USB Gadget controller hardware
+ *
+ * Almost everything can be done with only read and write operations,
+ * on endpoint files found in one directory.  They are configured by
+ * writing descriptors, and then may be used for normal stream style
+ * i/o requests.  When ep0 is configured, the device can enumerate;
+ * when it's closed, the device disconnects from usb.
+ *
+ * Configuration and device descriptors get written to /dev/gadget/$CHIP,
+ * which may then be used to read usb_gadgetfs_event structs.  The driver
+ * may activate endpoints as it handles SET_CONFIGURATION setup events,
+ * or earlier; writing endpoint descriptors to /dev/gadget/$ENDPOINT
+ * then performing data transfers by reading or writing.
+ */
+
+/*
+ * Events are delivered on the ep0 file descriptor, if the user mode driver
+ * reads from this file descriptor after writing the descriptors.  Don't
+ * stop polling this descriptor, if you write that kind of driver.
+ */
+
+enum usb_gadgetfs_event_type {
+	GADGETFS_NOP = 0,
+
+	GADGETFS_CONNECT,
+	GADGETFS_DISCONNECT,
+	GADGETFS_SETUP,
+	GADGETFS_SUSPEND,
+	// and likely more !
+};
+
+struct usb_gadgetfs_event {
+	enum usb_gadgetfs_event_type	type;
+	union {
+		// NOP, DISCONNECT, SUSPEND: nothing
+		// ... some hardware can't report disconnection
+
+		// CONNECT: just the speed
+		enum usb_device_speed	speed;
+
+		// SETUP: packet; DATA phase i/o precedes next event
+		// (setup.bmRequestType & USB_DIR_IN) flags direction 
+		// ... includes SET_CONFIGURATION, SET_INTERFACE
+		struct usb_ctrlrequest	setup;
+	} u;
+};
+
+
+/* endpoint ioctls */
+
+/* IN transfers may be reported to the gadget driver as complete
+ * 	when the fifo is loaded, before the host reads the data;
+ * OUT transfers may be reported to the host's "client" driver as
+ * 	complete when they're sitting in the FIFO unread.
+ * THIS returns how many bytes are "unclaimed" in the endpoint fifo
+ * (needed for precise fault handling, when the hardware allows it)
+ */
+#define	GADGETFS_FIFO_STATUS	_IO('g',1)
+
+/* discards any unclaimed data in the fifo. */
+#define	GADGETFS_FIFO_FLUSH	_IO('g',2)
+
+/* resets endpoint halt+toggle; used to implement set_interface.
+ * some hardware (like pxa2xx) can't support this.
+ */
+#define	GADGETFS_CLEAR_HALT	_IO('g',3)
+
+
-- 
cgit v1.2.3