README

* What's this?

libusb-gadget is a simple wrapper around Linux USB GadgetFS[1], which enables
USB target development in userspace.  It allows developers to write a
trivial gadget in ~200 lines, while the original GadgetFS example[2]
is ~1700 lines.

* Requirements

- linux 2.6.XX

* Quick start

I assume that you are using Debian GNU/Linux.  Since the USB gadget
framework is not compiled in the stock kernel (as of 2.6.29-1), you
will need to generate a couple of kernel modules by hand:

 $ sudo apt-get install linux-source-2.6.XX linux-headers-2.6.XX
 $ cd /usr/src
 $ tar xf linux-source-2.6.XX.tar.bz2
 $ cd libusb-gadget/scripts
 $ ./generate-kernel-modules /usr/src/linux-source-2.6.XX

After successful build, you will find "dummy_hcd.ko" and
"gadgetfs.ko" in the current working directory.  You can load them with:

 $ sudo insmod dummy_hcd.ko
 $ sudo insmod gadgetfs.ko

and mount the GadgetFS:

 $ sudo mkdir /dev/gadget
 $ sudo mount -t gadgetfs none /dev/gadget

Now you can try libusb-gadget.

 $ cd libusb-gadget
 $ ./configure
 $ make

tests/ contains an example gadget.

 $ cd tests
 $ sudo ./loopback 00FF:0000 # VEND:PROD

On another terminal:

 $ cd libusb-gadget/tests
 $ sudo ./loopback-test 00FF:0000 # VEND:PROD

* Limitations

- Multithreading is necessary since /dev/gadget/$ENDPOINT (except for
  ep0) do not support polling.

- The endpoint number in the endpoint descriptor must be specified
  explicitly, while the kernel space API assigns them automatically.

- The max packet size is also mandatory in that descriptor.

* License

LGPLv3+.  See COPYING.LESSER for detail.

Footnotes: 
[1]  http://www.linux-usb.org/gadget/
[2]  http://www.linux-usb.org/gadget/usb.c

* Copyright

All files are under the copyright of:

Copyright (C) 2009 Daiki Ueno <ueno@unixuser.org>

except src/usbstring.[ch] which are based on the version by David
Brownell and under the copyright of:

Copyright (C) 2003 David Brownell