^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Linux USB gadget configured through configfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) 25th April 2013
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) be connected to a USB Host to extend it with additional functions like a serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) port or a mass storage capability.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) A gadget is seen by its host as a set of configurations, each of which contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) a number of interfaces which, from the gadget's perspective, are known as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) functions, each function representing e.g. a serial connection or a SCSI disk.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Linux provides a number of functions for gadgets to use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Creating a gadget means deciding what configurations there will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) and which functions each configuration will provide.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) Configfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) for the purpose of telling the kernel about the above mentioned decision.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) This document is about how to do it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) It also describes how configfs integration into gadget is designed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Requirements
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) In order for this to work configfs must be available, so CONFIGFS_FS must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) (The original post describing the first function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) made available through configfs can be seen here:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) http://www.spinics.net/lists/linux-usb/msg76388.html)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) $ modprobe libcomposite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) $ mount none $CONFIGFS_HOME -t configfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) where CONFIGFS_HOME is the mount point for configfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 1. Creating the gadgets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) For each gadget to be created its corresponding directory must be created::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) $ mkdir $CONFIGFS_HOME/usb_gadget/g1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) $ cd $CONFIGFS_HOME/usb_gadget/g1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Each gadget needs to have its vendor id <VID> and product id <PID> specified::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) $ echo <VID> > idVendor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) $ echo <PID> > idProduct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) A gadget also needs its serial number, manufacturer and product strings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) In order to have a place to store them, a strings subdirectory must be created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) for each language, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) $ mkdir strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Then the strings can be specified::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) $ echo <serial number> > strings/0x409/serialnumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) $ echo <manufacturer> > strings/0x409/manufacturer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) $ echo <product> > strings/0x409/product
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) 2. Creating the configurations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Each gadget will consist of a number of configurations, their corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) directories must be created:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) $ mkdir configs/<name>.<number>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) where <name> can be any string which is legal in a filesystem and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) <number> is the configuration's number, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) $ mkdir configs/c.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Each configuration also needs its strings, so a subdirectory must be created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) for each language, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) $ mkdir configs/c.1/strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Then the configuration string can be specified::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) $ echo <configuration> > configs/c.1/strings/0x409/configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Some attributes can also be set for a configuration, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) $ echo 120 > configs/c.1/MaxPower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 3. Creating the functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) The gadget will provide some functions, for each function its corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) directory must be created::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) $ mkdir functions/<name>.<instance name>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) where <name> corresponds to one of allowed function names and instance name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) is an arbitrary string allowed in a filesystem, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Each function provides its specific set of attributes, with either read-only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) or read-write access. Where applicable they need to be written to as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 4. Associating the functions with their configurations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) ------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) At this moment a number of gadgets is created, each of which has a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) configurations specified and a number of functions available. What remains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) is specifying which function is available in which configuration (the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) function can be used in multiple configurations). This is achieved with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) creating symbolic links::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) $ ln -s functions/<name>.<instance name> configs/<name>.<number>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) $ ln -s functions/ncm.usb0 configs/c.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 5. Enabling the gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) All the above steps serve the purpose of composing the gadget of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) configurations and functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) An example directory structure might look like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) ./strings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ./strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) ./strings/0x409/serialnumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ./strings/0x409/product
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ./strings/0x409/manufacturer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ./configs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) ./configs/c.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ./configs/c.1/strings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) ./configs/c.1/strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) ./configs/c.1/strings/0x409/configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ./configs/c.1/bmAttributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ./configs/c.1/MaxPower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) ./functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) ./functions/ncm.usb0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) ./functions/ncm.usb0/ifname
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ./functions/ncm.usb0/qmult
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ./functions/ncm.usb0/host_addr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) ./functions/ncm.usb0/dev_addr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ./UDC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) ./bcdUSB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) ./bcdDevice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) ./idProduct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) ./idVendor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) ./bMaxPacketSize0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) ./bDeviceProtocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ./bDeviceSubClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) ./bDeviceClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Such a gadget must be finally enabled so that the USB host can enumerate it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) In order to enable the gadget it must be bound to a UDC (USB Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Controller)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) $ echo <udc name> > UDC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) where <udc name> is one of those found in /sys/class/udc/*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) $ echo s3c-hsotg > UDC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 6. Disabling the gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) $ echo "" > UDC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 7. Cleaning up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) Remove functions from configurations::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) $ rm configs/<config name>.<number>/<function>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) where <config name>.<number> specify the configuration and <function> is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) a symlink to a function being removed from the configuration, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) $ rm configs/c.1/ncm.usb0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) Remove strings directories in configurations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) $ rmdir configs/<config name>.<number>/strings/<lang>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) $ rmdir configs/c.1/strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) and remove the configurations::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) $ rmdir configs/<config name>.<number>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) rmdir configs/c.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) Remove functions (function modules are not unloaded, though):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) $ rmdir functions/<name>.<instance name>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) $ rmdir functions/ncm.usb0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) Remove strings directories in the gadget::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) $ rmdir strings/<lang>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) $ rmdir strings/0x409
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) and finally remove the gadget::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) $ cd ..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) $ rmdir <gadget name>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) $ rmdir g1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) Implementation design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) Below the idea of how configfs works is presented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) In configfs there are items and groups, both represented as directories.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) The difference between an item and a group is that a group can contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) other groups. In the picture below only an item is shown.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) Both items and groups can have attributes, which are represented as files.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) The user can create and remove directories, but cannot remove files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) which can be read-only or read-write, depending on what they represent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) The filesystem part of configfs operates on config_items/groups and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) configfs_attributes which are generic and of the same type for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) configured elements. However, they are embedded in usage-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) larger structures. In the picture below there is a "cs" which contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) a config_item and an "sa" which contains a configfs_attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) The filesystem view would be like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) ./
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) ./cs (directory)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) +--sa (file)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) Whenever a user reads/writes the "sa" file, a function is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) which accepts a struct config_item and a struct configfs_attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) In the said function the "cs" and "sa" are retrieved using the well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) known container_of technique and an appropriate sa's function (show or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) store) is called and passed the "cs" and a character buffer. The "show"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) is for displaying the file's contents (copy data from the cs to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) buffer), while the "store" is for modifying the file's contents (copy data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) from the buffer to the cs), but it is up to the implementer of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) two functions to decide what they actually do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) typedef struct configured_structure cs;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) typedef struct specific_attribute sa;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) sa
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) +----------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) cs | (*show)(cs *, buffer); |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) +-----------------+ | (*store)(cs *, buffer, length); |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) | | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) | +-------------+ | | +------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) | | struct |-|----|------>|struct | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) | | config_item | | | |configfs_attribute| |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) | +-------------+ | | +------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) | | +----------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) | data to be set | .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) | | .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) +-----------------+ .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) The file names are decided by the config item/group designer, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) the directories in general can be named at will. A group can have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) a number of its default sub-groups created automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) For more information on configfs please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) `Documentation/filesystems/configfs.rst`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) The concepts described above translate to USB gadgets like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) 1. A gadget has its config group, which has some attributes (idVendor,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) idProduct etc) and default sub-groups (configs, functions, strings).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Writing to the attributes causes the information to be stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) appropriate locations. In the configs, functions and strings sub-groups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) a user can create their sub-groups to represent configurations, functions,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) and groups of strings in a given language.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) 2. The user creates configurations and functions, in the configurations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) creates symbolic links to functions. This information is used when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) gadget's UDC attribute is written to, which means binding the gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) to the UDC. The code in drivers/usb/gadget/configfs.c iterates over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) all configurations, and in each configuration it iterates over all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) functions and binds them. This way the whole gadget is bound.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) 3. The file drivers/usb/gadget/configfs.c contains code for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) - gadget's config_group
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) - gadget's default groups (configs, functions, strings)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) - associating functions with configurations (symlinks)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) 4. Each USB function naturally has its own view of what it wants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) configured, so config_groups for particular functions are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) in the functions implementation files drivers/usb/gadget/f_*.c.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) 5. Function's code is written in such a way that it uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) usb_get_function_instance(), which, in turn, calls request_module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) So, provided that modprobe works, modules for particular functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) are loaded automatically. Please note that the converse is not true:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) after a gadget is disabled and torn down, the modules remain loaded.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags