| 1 | ====================
|
| 2 | How FunctionFS works
|
| 3 | ====================
|
| 4 |
|
| 5 | Overview
|
| 6 | ========
|
| 7 |
|
| 8 | From kernel point of view it is just a composite function with some
|
| 9 | unique behaviour. It may be added to an USB configuration only after
|
| 10 | the user space driver has registered by writing descriptors and
|
| 11 | strings (the user space program has to provide the same information
|
| 12 | that kernel level composite functions provide when they are added to
|
| 13 | the configuration).
|
| 14 |
|
| 15 | This in particular means that the composite initialisation functions
|
| 16 | may not be in init section (ie. may not use the __init tag).
|
| 17 |
|
| 18 | From user space point of view it is a file system which when
|
| 19 | mounted provides an "ep0" file. User space driver need to
|
| 20 | write descriptors and strings to that file. It does not need
|
| 21 | to worry about endpoints, interfaces or strings numbers but
|
| 22 | simply provide descriptors such as if the function was the
|
| 23 | only one (endpoints and strings numbers starting from one and
|
| 24 | interface numbers starting from zero). The FunctionFS changes
|
| 25 | them as needed also handling situation when numbers differ in
|
| 26 | different configurations.
|
| 27 |
|
| 28 | For more information about FunctionFS descriptors see :doc:`functionfs-desc`
|
| 29 |
|
| 30 | When descriptors and strings are written "ep#" files appear
|
| 31 | (one for each declared endpoint) which handle communication on
|
| 32 | a single endpoint. Again, FunctionFS takes care of the real
|
| 33 | numbers and changing of the configuration (which means that
|
| 34 | "ep1" file may be really mapped to (say) endpoint 3 (and when
|
| 35 | configuration changes to (say) endpoint 2)). "ep0" is used
|
| 36 | for receiving events and handling setup requests.
|
| 37 |
|
| 38 | When all files are closed the function disables itself.
|
| 39 |
|
| 40 | What I also want to mention is that the FunctionFS is designed in such
|
| 41 | a way that it is possible to mount it several times so in the end
|
| 42 | a gadget could use several FunctionFS functions. The idea is that
|
| 43 | each FunctionFS instance is identified by the device name used
|
| 44 | when mounting.
|
| 45 |
|
| 46 | One can imagine a gadget that has an Ethernet, MTP and HID interfaces
|
| 47 | where the last two are implemented via FunctionFS. On user space
|
| 48 | level it would look like this::
|
| 49 |
|
| 50 | $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
|
| 51 | $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
|
| 52 | $ ( cd /dev/ffs-mtp && mtp-daemon ) &
|
| 53 | $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
|
| 54 | $ ( cd /dev/ffs-hid && hid-daemon ) &
|
| 55 |
|
| 56 | On kernel level the gadget checks ffs_data->dev_name to identify
|
| 57 | whether its FunctionFS is designed for MTP ("mtp") or HID ("hid").
|
| 58 |
|
| 59 | If no "functions" module parameters is supplied, the driver accepts
|
| 60 | just one function with any name.
|
| 61 |
|
| 62 | When "functions" module parameter is supplied, only functions
|
| 63 | with listed names are accepted. In particular, if the "functions"
|
| 64 | parameter's value is just a one-element list, then the behaviour
|
| 65 | is similar to when there is no "functions" at all; however,
|
| 66 | only a function with the specified name is accepted.
|
| 67 |
|
| 68 | The gadget is registered only after all the declared function
|
| 69 | filesystems have been mounted and USB descriptors of all functions
|
| 70 | have been written to their ep0's.
|
| 71 |
|
| 72 | Conversely, the gadget is unregistered after the first USB function
|
| 73 | closes its endpoints.
|
| 74 |
|
| 75 | DMABUF interface
|
| 76 | ================
|
| 77 |
|
| 78 | FunctionFS additionally supports a DMABUF based interface, where the
|
| 79 | userspace can attach DMABUF objects (externally created) to an endpoint,
|
| 80 | and subsequently use them for data transfers.
|
| 81 |
|
| 82 | A userspace application can then use this interface to share DMABUF
|
| 83 | objects between several interfaces, allowing it to transfer data in a
|
| 84 | zero-copy fashion, for instance between IIO and the USB stack.
|
| 85 |
|
| 86 | As part of this interface, three new IOCTLs have been added. These three
|
| 87 | IOCTLs have to be performed on a data endpoint (ie. not ep0). They are:
|
| 88 |
|
| 89 | ``FUNCTIONFS_DMABUF_ATTACH(int)``
|
| 90 | Attach the DMABUF object, identified by its file descriptor, to the
|
| 91 | data endpoint. Returns zero on success, and a negative errno value
|
| 92 | on error.
|
| 93 |
|
| 94 | ``FUNCTIONFS_DMABUF_DETACH(int)``
|
| 95 | Detach the given DMABUF object, identified by its file descriptor,
|
| 96 | from the data endpoint. Returns zero on success, and a negative
|
| 97 | errno value on error. Note that closing the endpoint's file
|
| 98 | descriptor will automatically detach all attached DMABUFs.
|
| 99 |
|
| 100 | ``FUNCTIONFS_DMABUF_TRANSFER(struct usb_ffs_dmabuf_transfer_req *)``
|
| 101 | Enqueue the previously attached DMABUF to the transfer queue.
|
| 102 | The argument is a structure that packs the DMABUF's file descriptor,
|
| 103 | the size in bytes to transfer (which should generally correspond to
|
| 104 | the size of the DMABUF), and a 'flags' field which is unused
|
| 105 | for now. Returns zero on success, and a negative errno value on
|
| 106 | error.
|