diff options
author | Linus Torvalds | 2019-07-12 00:40:06 +0200 |
---|---|---|
committer | Linus Torvalds | 2019-07-12 00:40:06 +0200 |
commit | 17a20acaf171124017f43bc70bb4d7ca88070659 (patch) | |
tree | 8bc639ee52ed71fcfb32496dd4f16e03bdbf29b4 /Documentation/usb/functionfs.rst | |
parent | Merge tag 'tty-5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/greg... (diff) | |
parent | Merge tag 'usb-ci-v5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/... (diff) | |
download | kernel-qcow2-linux-17a20acaf171124017f43bc70bb4d7ca88070659.tar.gz kernel-qcow2-linux-17a20acaf171124017f43bc70bb4d7ca88070659.tar.xz kernel-qcow2-linux-17a20acaf171124017f43bc70bb4d7ca88070659.zip |
Merge tag 'usb-5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb
Pull USB / PHY updates from Greg KH:
"Here is the big USB and PHY driver pull request for 5.3-rc1.
Lots of stuff here, all of which has been in linux-next for a while
with no reported issues. Nothing is earth-shattering, just constant
forward progress for more devices supported and cleanups and small
fixes:
- USB gadget driver updates and fixes
- new USB gadget driver for some hardware, followed by a quick revert
of those patches as they were not ready to be merged...
- PHY driver updates
- Lots of new driver additions and cleanups with a few fixes mixed
in"
* tag 'usb-5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb: (145 commits)
Revert "usb: gadget: storage: Remove warning message"
Revert "dt-bindings: add binding for USBSS-DRD controller."
Revert "usb:gadget Separated decoding functions from dwc3 driver."
Revert "usb:gadget Patch simplify usb_decode_set_clear_feature function."
Revert "usb:gadget Simplify usb_decode_get_set_descriptor function."
Revert "usb:cdns3 Add Cadence USB3 DRD Driver"
Revert "usb:cdns3 Fix for stuck packets in on-chip OUT buffer."
usb :fsl: Change string format for errata property
usb: host: Stops USB controller init if PLL fails to lock
usb: linux/fsl_device: Add platform member has_fsl_erratum_a006918
usb: phy: Workaround for USB erratum-A005728
usb: fsl: Set USB_EN bit to select ULPI phy
usb: Handle USB3 remote wakeup for LPM enabled devices correctly
drivers/usb/typec/tps6598x.c: fix 4CC cmd write
drivers/usb/typec/tps6598x.c: fix portinfo width
usb: storage: scsiglue: Do not skip VPD if try_vpd_pages is set
usb: renesas_usbhs: add a workaround for a race condition of workqueue
usb: gadget: udc: renesas_usb3: remove redundant assignment to ret
usb: dwc2: use a longer AHB idle timeout in dwc2_core_reset()
USB: gadget: function: fix issue Unneeded variable: "value"
...
Diffstat (limited to 'Documentation/usb/functionfs.rst')
-rw-r--r-- | Documentation/usb/functionfs.rst | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/Documentation/usb/functionfs.rst b/Documentation/usb/functionfs.rst new file mode 100644 index 000000000000..7fdc6d840ac5 --- /dev/null +++ b/Documentation/usb/functionfs.rst @@ -0,0 +1,68 @@ +==================== +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. |