summaryrefslogtreecommitdiffstats
path: root/Documentation/usb/functionfs.rst
diff options
context:
space:
mode:
authorLinus Torvalds2019-07-12 00:40:06 +0200
committerLinus Torvalds2019-07-12 00:40:06 +0200
commit17a20acaf171124017f43bc70bb4d7ca88070659 (patch)
tree8bc639ee52ed71fcfb32496dd4f16e03bdbf29b4 /Documentation/usb/functionfs.rst
parentMerge tag 'tty-5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/greg... (diff)
parentMerge tag 'usb-ci-v5.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/... (diff)
downloadkernel-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.rst68
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.