diff options
Diffstat (limited to 'Documentation/usb')
| -rw-r--r-- | Documentation/usb/URB.txt | 22 | ||||
| -rw-r--r-- | Documentation/usb/functionfs.txt | 67 | ||||
| -rw-r--r-- | Documentation/usb/usbmon.txt | 6 |
3 files changed, 92 insertions, 3 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index 8ffce746d496..00d2c644068e 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt @@ -168,6 +168,28 @@ that if the completion handler or anyone else tries to resubmit it they will get a -EPERM error. Thus you can be sure that when usb_kill_urb() returns, the URB is totally idle. +There is a lifetime issue to consider. An URB may complete at any +time, and the completion handler may free the URB. If this happens +while usb_unlink_urb or usb_kill_urb is running, it will cause a +memory-access violation. The driver is responsible for avoiding this, +which often means some sort of lock will be needed to prevent the URB +from being deallocated while it is still in use. + +On the other hand, since usb_unlink_urb may end up calling the +completion handler, the handler must not take any lock that is held +when usb_unlink_urb is invoked. The general solution to this problem +is to increment the URB's reference count while holding the lock, then +drop the lock and call usb_unlink_urb or usb_kill_urb, and then +decrement the URB's reference count. You increment the reference +count by calling + + struct urb *usb_get_urb(struct urb *urb) + +(ignore the return value; it is the same as the argument) and +decrement the reference count by calling usb_free_urb. Of course, +none of this is necessary if there's no danger of the URB being freed +by the completion handler. + 1.7. What about the completion handler? diff --git a/Documentation/usb/functionfs.txt b/Documentation/usb/functionfs.txt new file mode 100644 index 000000000000..eaaaea019fc7 --- /dev/null +++ b/Documentation/usb/functionfs.txt @@ -0,0 +1,67 @@ +*How FunctionFS works* + +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: + +$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid +$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp +$ ( cd /dev/ffs-mtp && mtp-daemon ) & +$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid +$ ( cd /dev/ffs-hid && hid-daemon ) & + +On kernel level the gadget checks ffs_data->dev_name to identify +whether it's FunctionFS 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. + diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 5335fa8b06eb..c42bb9cd3b43 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -183,10 +183,10 @@ An input control transfer to get a port status. d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 -An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper -to a storage device at address 5: +An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte +Bulk wrapper to a storage device at address 5: -dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 +dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 dd65f0e8 4128379808 C Bo:1:005:2 0 31 > * Raw binary format and API |