The idea is to delegate actual USB function implementation to userspace, using a filesystem interface (read()/write() etc). This way, USB out traffic (from host) is available at a file descriptor ready for reading, and USB in traffic (to host) is accepted at a file descriptor ready for writing.
...
Now that you know about endpoints, you can learn more about FunctionFS. From the point of view of the gadget it is yet another USB function available for composing a gadget from. But it is special, because each instance of FunctionFS provides an instance of a 'functionfs' filesystem to be mounted. If you mount it you will notice there is only one entry: ep0. Its name suggests it is associated with endpoint 0. Indeed it is. However, the good news is that you don't need to implement all the endpoint 0 handling, because most of that is already taken care of for you by the composite layer. You only need to handle control requests directed at your particular USB function. ep0 is also (ab)used to specify the endpoints and USB strings. FunctionFS is not considered ready for binding until endpoint descriptors and strings are written to ep0. The gadget as a whole is not ready for binding if any of its functions is not ready. After the descriptors and strings are written, FunctionFS creates appropriate number of ep<number> files for you to use to implement the desired data streams between the host and the device.
An example function can be found in kernel sources: tools/usb/ffs-test.c The file also contains an example of how to specify USB descriptors and strings to be written to ep0 to make FunctionFS ready. Actually I'm using its modified and simplified version, which passes to the host whatever the host writes to it. We will get to its code later in this post.
How FunctionFS works — The Linux Kernel documentation
From kernel point of view it is just a composite function with some unique behaviour. It may be added to an USB configuration only after the user space driver has registered by writing descriptors and strings (the user space program has to provide the same information that kernel level composite functions provide when they are added to the configuration).
This in particular means that the composite initialisation functions may not be in init section (ie. may not use the __init tag).
From user space point of view it is a file system which when mounted provides an "ep0" file. User space driver need to write descriptors and strings to that file. It does not need to worry about endpoints, interfaces or strings numbers but simply provide descriptors such as if the function was the only one (endpoints and strings numbers starting from one and interface numbers starting from zero). The FunctionFS changes them as needed also handling situation when numbers differ in different configurations.
When descriptors and strings are written "ep#" files appear (one for each declared endpoint) which handle communication on a single endpoint. Again, FunctionFS takes care of the real numbers and changing of the configuration (which means that "ep1" file may be really mapped to (say) endpoint 3 (and when configuration changes to (say) endpoint 2)). "ep0" is used for receiving events and handling setup requests.
When all files are closed the function disables itself.
What I also want to mention is that the FunctionFS is designed in such a way that it is possible to mount it several times so in the end a gadget could use several FunctionFS functions. The idea is that each FunctionFS instance is identified by the device name used when mounting.
One can imagine a gadget that has an Ethernet, MTP and HID interfaces where the last two are implemented via FunctionFS. On user space level it would look like this:
On kernel level the gadget checks ffs_data->dev_name to identify whether its FunctionFS is designed for MTP ("mtp") or HID ("hid").
If no "functions" module parameters is supplied, the driver accepts just one function with any name.
When "functions" module parameter is supplied, only functions with listed names are accepted. In particular, if the "functions" parameter's value is just a one-element list, then the behaviour is similar to when there is no "functions" at all; however, only a function with the specified name is accepted.
The gadget is registered only after all the declared function filesystems have been mounted and USB descriptors of all functions have been written to their ep0's.
Conversely, the gadget is unregistered after the first USB function closes its endpoints.
ADB daemon on top of FunctionFS
FunctionFS: initial implementation This is the second version of a patch which demonstrates the possibility of using adbd (Android Debug Bridge daemon) with a generic FunctionFS gadget instead of a custom adb usb gadget in the Linux kernel. It contains changes introduced after Benoit's review - thank you Benoit. The patch adds a replacement usb access layer to adbd: it adds a new layer as a copy of an existing usb_linux_client.c and introduces FunctionFS support proper on top of the copied layer. The former usb access method is still available, the method is chosen at compilation time by setting USE_USB_FUNCFS variable to false in adb's Android.mk in the section dedicated to adbd. How to use on the target device: $ insmod g_ffs.ko idVendor=<vendor ID> iSerialNumber=<some string> $ mount -t functionfs adb /dev/usbgadget/adb -o uid=2000,gid=2000 $ ./adbd The Linux kernel 3.2 release's drivers/usb/gadget/composite.c contains module parameter definitions for idVendor and iSerialNumber and was verified to work. "adb devices" issued on host will list <some string> as the device name. In case adbd does not switch its identity to uid=2000,gid=2000, respective options are not required in the mount command above. It depends on adb properties. If adbd is run standalone (no more Android stuff), then the properties are set to their defaults which imply switching uid,gid to 2000,2000. By default old behaviour is compiled in. This can be changed by setting USE_USB_FUNCFS to true in Android.mk. This patch requires a patch to bionic which adds <linux/usb_functionfs.h> which is an exact copy of the relevant file in the linux kernel. Signed-off-by: Andrzej Pietrasiewicz <andrzej.p@samsung.com> Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com> Change-Id: I4b42eb267ffa50fca7a5fba46f388a2f083e8b2d
