1==================== 2How FunctionFS works 3==================== 4 5Overview 6======== 7 8From kernel point of view it is just a composite function with some 9unique behaviour. It may be added to an USB configuration only after 10the user space driver has registered by writing descriptors and 11strings (the user space program has to provide the same information 12that kernel level composite functions provide when they are added to 13the configuration). 14 15This in particular means that the composite initialisation functions 16may not be in init section (ie. may not use the __init tag). 17 18From user space point of view it is a file system which when 19mounted provides an "ep0" file. User space driver need to 20write descriptors and strings to that file. It does not need 21to worry about endpoints, interfaces or strings numbers but 22simply provide descriptors such as if the function was the 23only one (endpoints and strings numbers starting from one and 24interface numbers starting from zero). The FunctionFS changes 25them as needed also handling situation when numbers differ in 26different configurations. 27 28For more information about FunctionFS descriptors see :doc:`functionfs-desc` 29 30When descriptors and strings are written "ep#" files appear 31(one for each declared endpoint) which handle communication on 32a single endpoint. Again, FunctionFS takes care of the real 33numbers and changing of the configuration (which means that 34"ep1" file may be really mapped to (say) endpoint 3 (and when 35configuration changes to (say) endpoint 2)). "ep0" is used 36for receiving events and handling setup requests. 37 38When all files are closed the function disables itself. 39 40What I also want to mention is that the FunctionFS is designed in such 41a way that it is possible to mount it several times so in the end 42a gadget could use several FunctionFS functions. The idea is that 43each FunctionFS instance is identified by the device name used 44when mounting. 45 46One can imagine a gadget that has an Ethernet, MTP and HID interfaces 47where the last two are implemented via FunctionFS. On user space 48level 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 56On kernel level the gadget checks ffs_data->dev_name to identify 57whether its FunctionFS is designed for MTP ("mtp") or HID ("hid"). 58 59If no "functions" module parameters is supplied, the driver accepts 60just one function with any name. 61 62When "functions" module parameter is supplied, only functions 63with listed names are accepted. In particular, if the "functions" 64parameter's value is just a one-element list, then the behaviour 65is similar to when there is no "functions" at all; however, 66only a function with the specified name is accepted. 67 68The gadget is registered only after all the declared function 69filesystems have been mounted and USB descriptors of all functions 70have been written to their ep0's. 71 72Conversely, the gadget is unregistered after the first USB function 73closes its endpoints. 74 75Endpoint IOCTLs 76=============== 77 78FunctionFS supports additional IOCTLs that can be performed on data endpoints 79(ie. not ep0). For a full list of these IOCTLs, please refer to the documentation 80in ``include/uapi/linux/usb/functionfs.h``. 81 82One such IOCTL is: 83 84 ``FUNCTIONFS_ENDPOINT_ENABLE_ZLP(__u32 *)`` 85 Enable or disable automatic zero-length packet (ZLP) appending for the 86 endpoint. The argument is a pointer to a __u32: 0 to disable, non-zero to 87 enable. When enabled, the kernel will automatically append a ZLP at the end 88 of a transfer if the payload length is an exact multiple of the endpoint's 89 max packet size. This is useful for compatibility with legacy protocols 90 which require automatic ZLP appending to data written from userspace. This 91 IOCTL can only be used on IN endpoints. It can be called at any time after 92 the FunctionFS instance is active, even before the host has connected or 93 enabled the endpoint. Returns zero on success, or a negative errno value on 94 error: 95 96 * ``-ENODEV``: The FunctionFS instance is not active. 97 * ``-EINVAL``: The endpoint is not an IN endpoint. 98 * ``-EFAULT``: Invalid user space pointer for the argument. 99 100RW Proxy Endpoints 101================== 102 103If the ``FUNCTIONFS_RW_PROXY_EPS`` flag is passed in the descriptor header 104(requires ``FUNCTIONFS_DESCRIPTORS_MAGIC_V2``), FunctionFS will provision a 105bidirectional rw_proxy file descriptor (e.g., "ep1_rw") alongside each pair 106of IN and OUT endpoints. The rw_proxy file aliases the underlying hardware 107endpoints, allowing userspace to use a single file descriptor for both reading 108(OUT) and writing (IN). 109 110This flag requires the total number of hardware endpoints to be an even number. 111FunctionFS will automatically walk the provided endpoints and group them into 112adjacent pairs (e.g., ep1 and ep2 form the first pair, ep3 and ep4 form the 113second pair). Each pair must consist of exactly one IN endpoint and one OUT 114endpoint. 115 116For each valid pair, a rw_proxy file is created and named after the first 117endpoint in the pair with a "_rw" suffix. For example, if ep1 and ep2 are 118paired, a rw_proxy file named "ep1_rw" is created. If ep3 and ep4 are paired, 119"ep3_rw" is created. 120 121If the ``FUNCTIONFS_VIRTUAL_ADDR`` flag is also enabled, the endpoints will be 122named using their physical endpoint address in hexadecimal instead of their 123index. RW proxy files will inherit this naming convention. For example, if the 124first endpoint of a pair maps to address 0x02, the rw_proxy file will be 125named "ep02_rw". 126 127When this flag is enabled, userspace has the choice of performing data transfers 128via the single rw_proxy file descriptor or the two base file descriptors. The 129rw_proxy file descriptor acts as a pure VFS alias that proxies all operations 130directly to the underlying base file descriptors. 131 132Because it is a pure proxy, there are no data races or buffer corruptions if 133userspace uses both the rw_proxy endpoint and the base endpoints concurrently. 134The native mutexes of the base endpoints perfectly serialize all concurrent 135transfers. However, userspace should generally pick one method and stick to it 136to avoid interleaving its own data stream. 137 138- **IOCTLs (Clear Halt, etc.):** RW proxy endpoints do not support IOCTLs and 139 will return ``-ENOTTY``. To clear a host-initiated halt, userspace must issue 140 the ``FUNCTIONFS_CLEAR_HALT`` ioctl directly on the corresponding base 141 endpoint file descriptor. 142- **Intentional Stalls:** The traditional mechanism for intentionally halting an 143 endpoint by issuing a reverse-direction data operation (e.g., attempting to 144 read from an IN endpoint) continues to work, but it must be issued on the 145 base endpoint. RW proxy endpoints cannot be used to trigger a stall because 146 they are fully bidirectional. 147 148Note that DMABUF data transfers (``FUNCTIONFS_DMABUF_TRANSFER``) are unsupported 149via the rw_proxy endpoint because it does not support IOCTLs. If DMABUF 150transfers are required, users must use the standard base endpoints. 151DMABUF interface 152================ 153 154FunctionFS additionally supports a DMABUF based interface, where the 155userspace can attach DMABUF objects (externally created) to an endpoint, 156and subsequently use them for data transfers. 157 158Note: The DMABUF interface is unsupported on rw_proxy endpoints. See 159the RW Proxy Endpoints section for details on using DMABUF alongside 160the ``FUNCTIONFS_RW_PROXY_EPS`` flag. 161 162A userspace application can then use this interface to share DMABUF 163objects between several interfaces, allowing it to transfer data in a 164zero-copy fashion, for instance between IIO and the USB stack. 165 166As part of this interface, three new IOCTLs have been added. These three 167IOCTLs have to be performed on a data endpoint (ie. not ep0). They are: 168 169 ``FUNCTIONFS_DMABUF_ATTACH(int)`` 170 Attach the DMABUF object, identified by its file descriptor, to the 171 data endpoint. Returns zero on success, and a negative errno value 172 on error. 173 174 ``FUNCTIONFS_DMABUF_DETACH(int)`` 175 Detach the given DMABUF object, identified by its file descriptor, 176 from the data endpoint. Returns zero on success, and a negative 177 errno value on error. Note that closing the endpoint's file 178 descriptor will automatically detach all attached DMABUFs. 179 180 ``FUNCTIONFS_DMABUF_TRANSFER(struct usb_ffs_dmabuf_transfer_req *)`` 181 Enqueue the previously attached DMABUF to the transfer queue. 182 The argument is a structure that packs the DMABUF's file descriptor, 183 the size in bytes to transfer (which should generally correspond to 184 the size of the DMABUF), and a 'flags' field which is unused 185 for now. Returns zero on success, and a negative errno value on 186 error. 187