1ecefae6dSMauro Carvalho Chehab==================== 2ecefae6dSMauro Carvalho ChehabHow FunctionFS works 3ecefae6dSMauro Carvalho Chehab==================== 4ecefae6dSMauro Carvalho Chehab 5ecefae6dSMauro Carvalho ChehabFrom kernel point of view it is just a composite function with some 6ecefae6dSMauro Carvalho Chehabunique behaviour. It may be added to an USB configuration only after 7ecefae6dSMauro Carvalho Chehabthe user space driver has registered by writing descriptors and 8ecefae6dSMauro Carvalho Chehabstrings (the user space program has to provide the same information 9ecefae6dSMauro Carvalho Chehabthat kernel level composite functions provide when they are added to 10ecefae6dSMauro Carvalho Chehabthe configuration). 11ecefae6dSMauro Carvalho Chehab 12ecefae6dSMauro Carvalho ChehabThis in particular means that the composite initialisation functions 13ecefae6dSMauro Carvalho Chehabmay not be in init section (ie. may not use the __init tag). 14ecefae6dSMauro Carvalho Chehab 15ecefae6dSMauro Carvalho ChehabFrom user space point of view it is a file system which when 16ecefae6dSMauro Carvalho Chehabmounted provides an "ep0" file. User space driver need to 17ecefae6dSMauro Carvalho Chehabwrite descriptors and strings to that file. It does not need 18ecefae6dSMauro Carvalho Chehabto worry about endpoints, interfaces or strings numbers but 19ecefae6dSMauro Carvalho Chehabsimply provide descriptors such as if the function was the 20ecefae6dSMauro Carvalho Chehabonly one (endpoints and strings numbers starting from one and 21ecefae6dSMauro Carvalho Chehabinterface numbers starting from zero). The FunctionFS changes 22ecefae6dSMauro Carvalho Chehabthem as needed also handling situation when numbers differ in 23ecefae6dSMauro Carvalho Chehabdifferent configurations. 24ecefae6dSMauro Carvalho Chehab 25ecefae6dSMauro Carvalho ChehabWhen descriptors and strings are written "ep#" files appear 26ecefae6dSMauro Carvalho Chehab(one for each declared endpoint) which handle communication on 27ecefae6dSMauro Carvalho Chehaba single endpoint. Again, FunctionFS takes care of the real 28ecefae6dSMauro Carvalho Chehabnumbers and changing of the configuration (which means that 29ecefae6dSMauro Carvalho Chehab"ep1" file may be really mapped to (say) endpoint 3 (and when 30ecefae6dSMauro Carvalho Chehabconfiguration changes to (say) endpoint 2)). "ep0" is used 31ecefae6dSMauro Carvalho Chehabfor receiving events and handling setup requests. 32ecefae6dSMauro Carvalho Chehab 33ecefae6dSMauro Carvalho ChehabWhen all files are closed the function disables itself. 34ecefae6dSMauro Carvalho Chehab 35ecefae6dSMauro Carvalho ChehabWhat I also want to mention is that the FunctionFS is designed in such 36ecefae6dSMauro Carvalho Chehaba way that it is possible to mount it several times so in the end 37ecefae6dSMauro Carvalho Chehaba gadget could use several FunctionFS functions. The idea is that 38ecefae6dSMauro Carvalho Chehabeach FunctionFS instance is identified by the device name used 39ecefae6dSMauro Carvalho Chehabwhen mounting. 40ecefae6dSMauro Carvalho Chehab 41ecefae6dSMauro Carvalho ChehabOne can imagine a gadget that has an Ethernet, MTP and HID interfaces 42ecefae6dSMauro Carvalho Chehabwhere the last two are implemented via FunctionFS. On user space 43ecefae6dSMauro Carvalho Chehablevel it would look like this:: 44ecefae6dSMauro Carvalho Chehab 45ecefae6dSMauro Carvalho Chehab $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid 46ecefae6dSMauro Carvalho Chehab $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp 47ecefae6dSMauro Carvalho Chehab $ ( cd /dev/ffs-mtp && mtp-daemon ) & 48ecefae6dSMauro Carvalho Chehab $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid 49ecefae6dSMauro Carvalho Chehab $ ( cd /dev/ffs-hid && hid-daemon ) & 50ecefae6dSMauro Carvalho Chehab 51ecefae6dSMauro Carvalho ChehabOn kernel level the gadget checks ffs_data->dev_name to identify 52*f13039ceSRandy Dunlapwhether its FunctionFS is designed for MTP ("mtp") or HID ("hid"). 53ecefae6dSMauro Carvalho Chehab 54ecefae6dSMauro Carvalho ChehabIf no "functions" module parameters is supplied, the driver accepts 55ecefae6dSMauro Carvalho Chehabjust one function with any name. 56ecefae6dSMauro Carvalho Chehab 57ecefae6dSMauro Carvalho ChehabWhen "functions" module parameter is supplied, only functions 58ecefae6dSMauro Carvalho Chehabwith listed names are accepted. In particular, if the "functions" 59ecefae6dSMauro Carvalho Chehabparameter's value is just a one-element list, then the behaviour 60ecefae6dSMauro Carvalho Chehabis similar to when there is no "functions" at all; however, 61ecefae6dSMauro Carvalho Chehabonly a function with the specified name is accepted. 62ecefae6dSMauro Carvalho Chehab 63ecefae6dSMauro Carvalho ChehabThe gadget is registered only after all the declared function 64ecefae6dSMauro Carvalho Chehabfilesystems have been mounted and USB descriptors of all functions 65ecefae6dSMauro Carvalho Chehabhave been written to their ep0's. 66ecefae6dSMauro Carvalho Chehab 67ecefae6dSMauro Carvalho ChehabConversely, the gadget is unregistered after the first USB function 68ecefae6dSMauro Carvalho Chehabcloses its endpoints. 69