Ӥsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}(hhparenthuba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/usb/gadget_configfsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}(hhhh2ubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/usb/gadget_configfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}(hhhhFubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/usb/gadget_configfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}(hhhhZubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/usb/gadget_configfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}(hhhhnubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/usb/gadget_configfsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}(hhhhubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/usb/gadget_configfsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h,Linux USB gadget configured through configfsh]h,Linux USB gadget configured through configfs}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhA/var/lib/git/docbuild/linux/Documentation/usb/gadget_configfs.rsthKubh paragraph)}(h25th April 2013h]h25th April 2013}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hOverviewh]hOverview}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(hA USB Linux Gadget is a device which has a UDC (USB Device Controller) and can be connected to a USB Host to extend it with additional functions like a serial port or a mass storage capability.h]hA USB Linux Gadget is a device which has a UDC (USB Device Controller) and can be connected to a USB Host to extend it with additional functions like a serial port or a mass storage capability.}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hA gadget is seen by its host as a set of configurations, each of which contains a number of interfaces which, from the gadget's perspective, are known as functions, each function representing e.g. a serial connection or a SCSI disk.h]hA gadget is seen by its host as a set of configurations, each of which contains a number of interfaces which, from the gadget’s perspective, are known as functions, each function representing e.g. a serial connection or a SCSI disk.}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h8Linux provides a number of functions for gadgets to use.h]h8Linux provides a number of functions for gadgets to use.}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hwCreating a gadget means deciding what configurations there will be and which functions each configuration will provide.h]hwCreating a gadget means deciding what configurations there will be and which functions each configuration will provide.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hConfigfs (please see `Documentation/filesystems/configfs.rst`) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it.h](hConfigfs (please see }(hConfigfs (please see hjhhhNhNubhtitle_reference)}(h(`Documentation/filesystems/configfs.rst`h]h&Documentation/filesystems/configfs.rst}(hhhjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it.}(h) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it.hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hCIt also describes how configfs integration into gadget is designed.h]hCIt also describes how configfs integration into gadget is designed.}(hj6hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]overviewah ]h"]overviewah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h Requirementsh]h Requirements}(hjOhjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhK%ubh)}(hIn order for this to work configfs must be available, so CONFIGFS_FS must be 'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.h]hIn order for this to work configfs must be available, so CONFIGFS_FS must be ‘y’ or ‘m’ in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS.}(hj]hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hjJhhubeh}(h] requirementsah ]h"] requirementsah$]h&]uh1hhhhhhhhK%ubh)}(hhh](h)}(hUsageh]hUsage}(hjvhjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjqhhhhhK.ubh)}(h(The original post describing the first function made available through configfs can be seen here: http://www.spinics.net/lists/linux-usb/msg76388.html)h](hc(The original post describing the first function made available through configfs can be seen here: }(hc(The original post describing the first function made available through configfs can be seen here: hjhhhNhNubh reference)}(h4http://www.spinics.net/lists/linux-usb/msg76388.htmlh]h4http://www.spinics.net/lists/linux-usb/msg76388.html}(hhhjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubh)}(h)hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK0hjqhhubh literal_block)}(h?$ modprobe libcomposite $ mount none $CONFIGFS_HOME -t configfsh]h?$ modprobe libcomposite $ mount none $CONFIGFS_HOME -t configfs}(hhhjubah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhK6hjqhhubh)}(h3where CONFIGFS_HOME is the mount point for configfsh]h3where CONFIGFS_HOME is the mount point for configfs}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjqhhubh)}(hhh](h)}(h1. Creating the gadgetsh]h1. Creating the gadgets}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKhjhhubj)}(h/$ mkdir $CONFIGFS_HOME/usb_gadget/h]h/$ mkdir $CONFIGFS_HOME/usb_gadget/}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhK@hjhhubh)}(he.g.::h]he.g.:}(he.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjhhubj)}(hT$ mkdir $CONFIGFS_HOME/usb_gadget/g1 ... ... ... $ cd $CONFIGFS_HOME/usb_gadget/g1h]hT$ mkdir $CONFIGFS_HOME/usb_gadget/g1 ... ... ... $ cd $CONFIGFS_HOME/usb_gadget/g1}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKDhjhhubh)}(hNEach gadget needs to have its vendor id and product id specified::h]hMEach gadget needs to have its vendor id and product id specified:}(hMEach gadget needs to have its vendor id and product id specified:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjhhubj)}(h0$ echo > idVendor $ echo > idProducth]h0$ echo > idVendor $ echo > idProduct}(hhhj!ubah}(h]h ]h"]h$]h&]jjuh1jhhhKNhjhhubh)}(hA gadget also needs its serial number, manufacturer and product strings. In order to have a place to store them, a strings subdirectory must be created for each language, e.g.::h]hA gadget also needs its serial number, manufacturer and product strings. In order to have a place to store them, a strings subdirectory must be created for each language, e.g.:}(hA gadget also needs its serial number, manufacturer and product strings. In order to have a place to store them, a strings subdirectory must be created for each language, e.g.:hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhjhhubj)}(h$ mkdir strings/0x409h]h$ mkdir strings/0x409}(hhhj>ubah}(h]h ]h"]h$]h&]jjuh1jhhhKUhjhhubh)}(h#Then the strings can be specified::h]h"Then the strings can be specified:}(h"Then the strings can be specified:hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKWhjhhubj)}(h$ echo > strings/0x409/serialnumber $ echo > strings/0x409/manufacturer $ echo > strings/0x409/producth]h$ echo > strings/0x409/serialnumber $ echo > strings/0x409/manufacturer $ echo > strings/0x409/product}(hhhj[ubah}(h]h ]h"]h$]h&]jjuh1jhhhKYhjhhubh)}(hFurther custom string descriptors can be created as directories within the language's directory, with the string text being written to the "s" attribute within the string's directory:h]hFurther custom string descriptors can be created as directories within the language’s directory, with the string text being written to the “s” attribute within the string’s directory:}(hjkhjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjhhubh block_quote)}(hhh]h)}(hF$ mkdir strings/0x409/xu.0 $ echo > strings/0x409/xu.0/sh]hF$ mkdir strings/0x409/xu.0 $ echo > strings/0x409/xu.0/s}(hj~hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKahjyubah}(h]h ]h"]h$]h&]uh1jwhjhhhhhNubh)}(hWhere function drivers support it, functions may allow symlinks to these custom string descriptors to associate those strings with class descriptors.h]hWhere function drivers support it, functions may allow symlinks to these custom string descriptors to associate those strings with class descriptors.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKdhjhhubeh}(h]creating-the-gadgetsah ]h"]1. creating the gadgetsah$]h&]uh1hhjqhhhhhK.h]h$ mkdir configs/.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjhhubh)}(htwhere can be any string which is legal in a filesystem and the is the configuration's number, e.g.::h]huwhere can be any string which is legal in a filesystem and the is the configuration’s number, e.g.:}(hswhere can be any string which is legal in a filesystem and the is the configuration's number, e.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjhhubj)}(h $ mkdir configs/c.1 ... ... ...h]h $ mkdir configs/c.1 ... ... ...}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKrhjhhubh)}(hfEach configuration also needs its strings, so a subdirectory must be created for each language, e.g.::h]heEach configuration also needs its strings, so a subdirectory must be created for each language, e.g.:}(heEach configuration also needs its strings, so a subdirectory must be created for each language, e.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjhhubj)}(h!$ mkdir configs/c.1/strings/0x409h]h!$ mkdir configs/c.1/strings/0x409}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhK{hjhhubh)}(h0Then the configuration string can be specified::h]h/Then the configuration string can be specified:}(h/Then the configuration string can be specified:hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubj)}(h@$ echo > configs/c.1/strings/0x409/configurationh]h@$ echo > configs/c.1/strings/0x409/configuration}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h;Some attributes can also be set for a configuration, e.g.::h]h:Some attributes can also be set for a configuration, e.g.:}(h:Some attributes can also be set for a configuration, e.g.:hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h!$ echo 120 > configs/c.1/MaxPowerh]h!$ echo 120 > configs/c.1/MaxPower}(hhhj9ubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h]creating-the-configurationsah ]h"]2. creating the configurationsah$]h&]uh1hhjqhhhhhKhubh)}(hhh](h)}(h3. Creating the functionsh]h3. Creating the functions}(hjThjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjOhhhhhKubh)}(hgThe gadget will provide some functions, for each function its corresponding directory must be created::h]hfThe gadget will provide some functions, for each function its corresponding directory must be created:}(hfThe gadget will provide some functions, for each function its corresponding directory must be created:hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubj)}(h($ mkdir functions/.h]h($ mkdir functions/.}(hhhjoubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjOhhubh)}(hwhere corresponds to one of allowed function names and instance name is an arbitrary string allowed in a filesystem, e.g.::h]hwhere corresponds to one of allowed function names and instance name is an arbitrary string allowed in a filesystem, e.g.:}(hwhere corresponds to one of allowed function names and instance name is an arbitrary string allowed in a filesystem, e.g.:hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubj)}(hX$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() ... ... ...h]hX$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() ... ... ...}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjOhhubh)}(hEach function provides its specific set of attributes, with either read-only or read-write access. Where applicable they need to be written to as appropriate. Please refer to Documentation/ABI/testing/configfs-usb-gadget for more information.h]hEach function provides its specific set of attributes, with either read-only or read-write access. Where applicable they need to be written to as appropriate. Please refer to Documentation/ABI/testing/configfs-usb-gadget for more information.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubeh}(h]creating-the-functionsah ]h"]3. creating the functionsah$]h&]uh1hhjqhhhhhKubh)}(hhh](h)}(h64. Associating the functions with their configurationsh]h64. Associating the functions with their configurations}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXDAt this moment a number of gadgets is created, each of which has a number of configurations specified and a number of functions available. What remains is specifying which function is available in which configuration (the same function can be used in multiple configurations). This is achieved with creating symbolic links::h]hXCAt this moment a number of gadgets is created, each of which has a number of configurations specified and a number of functions available. What remains is specifying which function is available in which configuration (the same function can be used in multiple configurations). This is achieved with creating symbolic links:}(hXCAt this moment a number of gadgets is created, each of which has a number of configurations specified and a number of functions available. What remains is specifying which function is available in which configuration (the same function can be used in multiple configurations). This is achieved with creating symbolic links:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h@$ ln -s functions/. configs/.h]h@$ ln -s functions/. configs/.}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(he.g.::h]he.g.:}(he.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h3$ ln -s functions/ncm.usb0 configs/c.1 ... ... ...h]h3$ ln -s functions/ncm.usb0 configs/c.1 ... ... ...}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h]3associating-the-functions-with-their-configurationsah ]h"]64. associating the functions with their configurationsah$]h&]uh1hhjqhhhhhKubh)}(hhh](h)}(h5. Enabling the gadgeth]h5. Enabling the gadget}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h^All the above steps serve the purpose of composing the gadget of configurations and functions.h]h^All the above steps serve the purpose of composing the gadget of configurations and functions.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h5An example directory structure might look like this::h]h4An example directory structure might look like this:}(h4An example directory structure might look like this:hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hXf. ./strings ./strings/0x409 ./strings/0x409/serialnumber ./strings/0x409/product ./strings/0x409/manufacturer ./configs ./configs/c.1 ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 ./configs/c.1/strings ./configs/c.1/strings/0x409 ./configs/c.1/strings/0x409/configuration ./configs/c.1/bmAttributes ./configs/c.1/MaxPower ./functions ./functions/ncm.usb0 ./functions/ncm.usb0/ifname ./functions/ncm.usb0/qmult ./functions/ncm.usb0/host_addr ./functions/ncm.usb0/dev_addr ./UDC ./bcdUSB ./bcdDevice ./idProduct ./idVendor ./bMaxPacketSize0 ./bDeviceProtocol ./bDeviceSubClass ./bDeviceClassh]hXf. ./strings ./strings/0x409 ./strings/0x409/serialnumber ./strings/0x409/product ./strings/0x409/manufacturer ./configs ./configs/c.1 ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 ./configs/c.1/strings ./configs/c.1/strings/0x409 ./configs/c.1/strings/0x409/configuration ./configs/c.1/bmAttributes ./configs/c.1/MaxPower ./functions ./functions/ncm.usb0 ./functions/ncm.usb0/ifname ./functions/ncm.usb0/qmult ./functions/ncm.usb0/host_addr ./functions/ncm.usb0/dev_addr ./UDC ./bcdUSB ./bcdDevice ./idProduct ./idVendor ./bMaxPacketSize0 ./bDeviceProtocol ./bDeviceSubClass ./bDeviceClass}(hhhj1ubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hLSuch a gadget must be finally enabled so that the USB host can enumerate it.h]hLSuch a gadget must be finally enabled so that the USB host can enumerate it.}(hjAhj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hQIn order to enable the gadget it must be bound to a UDC (USB Device Controller)::h]hPIn order to enable the gadget it must be bound to a UDC (USB Device Controller):}(hPIn order to enable the gadget it must be bound to a UDC (USB Device Controller):hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h$ echo > UDCh]h$ echo > UDC}(hhhj\ubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hAwhere is one of those found in /sys/class/udc/* e.g.::h]h@where is one of those found in /sys/class/udc/* e.g.:}(h@where is one of those found in /sys/class/udc/* e.g.:hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h$ echo s3c-hsotg > UDCh]h$ echo s3c-hsotg > UDC}(hhhjyubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h]enabling-the-gadgetah ]h"]5. enabling the gadgetah$]h&]uh1hhjqhhhhhKubh)}(hhh](h)}(h6. Disabling the gadgeth]h6. Disabling the gadget}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj)}(h$ echo "" > UDCh]h$ echo "" > UDC}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h]disabling-the-gadgetah ]h"]6. disabling the gadgetah$]h&]uh1hhjqhhhhhKubh)}(hhh](h)}(h7. Cleaning uph]h7. Cleaning up}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h&Remove functions from configurations::h]h%Remove functions from configurations:}(h%Remove functions from configurations:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h.$ rm configs/./h]h.$ rm configs/./}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hwhere . specify the configuration and is a symlink to a function being removed from the configuration, e.g.::h]hwhere . specify the configuration and is a symlink to a function being removed from the configuration, e.g.:}(hwhere . specify the configuration and is a symlink to a function being removed from the configuration, e.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h&$ rm configs/c.1/ncm.usb0 ... ... ...h]h&$ rm configs/c.1/ncm.usb0 ... ... ...}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h-Remove strings directories in configurations:h]h-Remove strings directories in configurations:}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjx)}(hhh]h)}(h5$ rmdir configs/./strings/h]h5$ rmdir configs/./strings/}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jwhjhhhhhNubh)}(he.g.::h]he.g.:}(he.g.:hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h.$ rmdir configs/c.1/strings/0x409 ... ... ...h]h.$ rmdir configs/c.1/strings/0x409 ... ... ...}(hhhj5ubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hand remove the configurations::h]hand remove the configurations:}(hand remove the configurations:hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h&$ rmdir configs/.h]h&$ rmdir configs/.}(hhhjRubah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(he.g.::h]he.g.:}(he.g.:hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubj)}(hrmdir configs/c.1 ... ... ...h]hrmdir configs/c.1 ... ... ...}(hhhjoubah}(h]h ]h"]h$]h&]jjuh1jhhhM hjhhubh)}(h=Remove functions (function modules are not unloaded, though):h]h=Remove functions (function modules are not unloaded, though):}(hjhj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjx)}(hhh]h)}(h($ rmdir functions/.h]h($ rmdir functions/.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jwhjhhhhhNubh)}(he.g.::h]he.g.:}(he.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h'$ rmdir functions/ncm.usb0 ... ... ...h]h'$ rmdir functions/ncm.usb0 ... ... ...}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(h*Remove strings directories in the gadget::h]h)Remove strings directories in the gadget:}(h)Remove strings directories in the gadget:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h$ rmdir strings/h]h$ rmdir strings/}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(he.g.::h]he.g.:}(he.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hjhhubj)}(h$ rmdir strings/0x409h]h$ rmdir strings/0x409}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhM#hjhhubh)}(hand finally remove the gadget::h]hand finally remove the gadget:}(hand finally remove the gadget:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjhhubj)}(h$ cd .. $ rmdir h]h$ cd .. $ rmdir }(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhM'hjhhubh)}(he.g.::h]he.g.:}(he.g.:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjhhubj)}(h $ rmdir g1h]h $ rmdir g1}(hhhj%ubah}(h]h ]h"]h$]h&]jjuh1jhhhM,hjhhubeh}(h] cleaning-upah ]h"]7. cleaning upah$]h&]uh1hhjqhhhhhKubeh}(h]usageah ]h"]usageah$]h&]uh1hhhhhhhhK.ubh)}(hhh](h)}(hImplementation designh]hImplementation design}(hjHhjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjChhhhhM2ubh)}(hXBelow the idea of how configfs works is presented. In configfs there are items and groups, both represented as directories. The difference between an item and a group is that a group can contain other groups. In the picture below only an item is shown. Both items and groups can have attributes, which are represented as files. The user can create and remove directories, but cannot remove files, which can be read-only or read-write, depending on what they represent.h]hXBelow the idea of how configfs works is presented. In configfs there are items and groups, both represented as directories. The difference between an item and a group is that a group can contain other groups. In the picture below only an item is shown. Both items and groups can have attributes, which are represented as files. The user can create and remove directories, but cannot remove files, which can be read-only or read-write, depending on what they represent.}(hjVhjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hjChhubh)}(hXNThe filesystem part of configfs operates on config_items/groups and configfs_attributes which are generic and of the same type for all configured elements. However, they are embedded in usage-specific larger structures. In the picture below there is a "cs" which contains a config_item and an "sa" which contains a configfs_attribute.h]hXVThe filesystem part of configfs operates on config_items/groups and configfs_attributes which are generic and of the same type for all configured elements. However, they are embedded in usage-specific larger structures. In the picture below there is a “cs” which contains a config_item and an “sa” which contains a configfs_attribute.}(hjdhjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hjChhubh)}(h(The filesystem view would be like this::h]h'The filesystem view would be like this:}(h'The filesystem view would be like this:hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMBhjChhubj)}(hF./ ./cs (directory) | +--sa (file) | . . .h]hF./ ./cs (directory) | +--sa (file) | . . .}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhMDhjChhubh)}(hXXWhenever a user reads/writes the "sa" file, a function is called which accepts a struct config_item and a struct configfs_attribute. In the said function the "cs" and "sa" are retrieved using the well known container_of technique and an appropriate sa's function (show or store) is called and passed the "cs" and a character buffer. The "show" is for displaying the file's contents (copy data from the cs to the buffer), while the "store" is for modifying the file's contents (copy data from the buffer to the cs), but it is up to the implementer of the two functions to decide what they actually do.h]hXvWhenever a user reads/writes the “sa” file, a function is called which accepts a struct config_item and a struct configfs_attribute. In the said function the “cs” and “sa” are retrieved using the well known container_of technique and an appropriate sa’s function (show or store) is called and passed the “cs” and a character buffer. The “show” is for displaying the file’s contents (copy data from the cs to the buffer), while the “store” is for modifying the file’s contents (copy data from the buffer to the cs), but it is up to the implementer of the two functions to decide what they actually do.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMMhjChhubj)}(hXtypedef struct configured_structure cs; typedef struct specific_attribute sa; sa +----------------------------------+ cs | (*show)(cs *, buffer); | +-----------------+ | (*store)(cs *, buffer, length); | | | | | | +-------------+ | | +------------------+ | | | struct |-|----|------>|struct | | | | config_item | | | |configfs_attribute| | | +-------------+ | | +------------------+ | | | +----------------------------------+ | data to be set | . | | . +-----------------+ .h]hXtypedef struct configured_structure cs; typedef struct specific_attribute sa; sa +----------------------------------+ cs | (*show)(cs *, buffer); | +-----------------+ | (*store)(cs *, buffer, length); | | | | | | +-------------+ | | +------------------+ | | | struct |-|----|------>|struct | | | | config_item | | | |configfs_attribute| | | +-------------+ | | +------------------+ | | | +----------------------------------+ | data to be set | . | | . +-----------------+ .}(hhhjubah}(h]h ]h"]h$]h&]jjuh1jhhhMYhjChhubh)}(hThe file names are decided by the config item/group designer, while the directories in general can be named at will. A group can have a number of its default sub-groups created automatically.h]hThe file names are decided by the config item/group designer, while the directories in general can be named at will. A group can have a number of its default sub-groups created automatically.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMjhjChhubh)}(hUFor more information on configfs please see `Documentation/filesystems/configfs.rst`.h](h,For more information on configfs please see }(h,For more information on configfs please see hjhhhNhNubj)}(h(`Documentation/filesystems/configfs.rst`h]h&Documentation/filesystems/configfs.rst}(hhhjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(h.hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMnhjChhubh)}(h@The concepts described above translate to USB gadgets like this:h]h@The concepts described above translate to USB gadgets like this:}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMqhjChhubh)}(hX1. A gadget has its config group, which has some attributes (idVendor, idProduct etc) and default sub-groups (configs, functions, strings). Writing to the attributes causes the information to be stored in appropriate locations. In the configs, functions and strings sub-groups a user can create their sub-groups to represent configurations, functions, and groups of strings in a given language.h]hX1. A gadget has its config group, which has some attributes (idVendor, idProduct etc) and default sub-groups (configs, functions, strings). Writing to the attributes causes the information to be stored in appropriate locations. In the configs, functions and strings sub-groups a user can create their sub-groups to represent configurations, functions, and groups of strings in a given language.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMshjChhubh)}(hX2. The user creates configurations and functions, in the configurations creates symbolic links to functions. This information is used when the gadget's UDC attribute is written to, which means binding the gadget to the UDC. The code in drivers/usb/gadget/configfs.c iterates over all configurations, and in each configuration it iterates over all functions and binds them. This way the whole gadget is bound.h]hX2. The user creates configurations and functions, in the configurations creates symbolic links to functions. This information is used when the gadget’s UDC attribute is written to, which means binding the gadget to the UDC. The code in drivers/usb/gadget/configfs.c iterates over all configurations, and in each configuration it iterates over all functions and binds them. This way the whole gadget is bound.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMzhjChhubhenumerated_list)}(hhh]h list_item)}(hThe file drivers/usb/gadget/configfs.c contains code for - gadget's config_group - gadget's default groups (configs, functions, strings) - associating functions with configurations (symlinks) h](h)}(h8The file drivers/usb/gadget/configfs.c contains code forh]h8The file drivers/usb/gadget/configfs.c contains code for}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubjx)}(hhh]h bullet_list)}(hhh](j )}(hgadget's config_grouph]h)}(hj&h]hgadget’s config_group}(hj&hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj$ubah}(h]h ]h"]h$]h&]uh1jhj!ubj )}(h5gadget's default groups (configs, functions, strings)h]h)}(hj=h]h7gadget’s default groups (configs, functions, strings)}(hj=hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj;ubah}(h]h ]h"]h$]h&]uh1jhj!ubj )}(h5associating functions with configurations (symlinks) h]h)}(h4associating functions with configurations (symlinks)h]h4associating functions with configurations (symlinks)}(hjXhjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjRubah}(h]h ]h"]h$]h&]uh1jhj!ubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jwhj ubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffixjstartKuh1jhjChhhhhMubh)}(h4. Each USB function naturally has its own view of what it wants configured, so config_groups for particular functions are defined in the functions implementation files drivers/usb/gadget/f_*.c.h]h4. Each USB function naturally has its own view of what it wants configured, so config_groups for particular functions are defined in the functions implementation files drivers/usb/gadget/f_*.c.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjChhubj)}(hhh]j )}(h6Function's code is written in such a way that it uses h]h)}(h5Function's code is written in such a way that it usesh]h7Function’s code is written in such a way that it uses}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jjjhjjjKuh1jhjChhhhhMubh)}(hXusb_get_function_instance(), which, in turn, calls request_module. So, provided that modprobe works, modules for particular functions are loaded automatically. Please note that the converse is not true: after a gadget is disabled and torn down, the modules remain loaded.h]hXusb_get_function_instance(), which, in turn, calls request_module. So, provided that modprobe works, modules for particular functions are loaded automatically. Please note that the converse is not true: after a gadget is disabled and torn down, the modules remain loaded.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjChhubeh}(h]implementation-designah ]h"]implementation designah$]h&]uh1hhhhhhhhM2ubeh}(h],linux-usb-gadget-configured-through-configfsah ]h"],linux usb gadget configured through configfsah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingUTF-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confapep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacefile_insertion_enabled raw_enabledKline_length_limitM'syntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_link embed_imagesenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjGjDjnjkj@j=jjjLjIjjjjjjjjj8j5jju nametypes}(jNjGNjnNj@NjNjLNjNjNjNjNj8NjNuh}(jhjDhjkjJj=jqjjjIjjjOjjjjjjj5jjjCu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages](hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "3" (ordinal 3)h]h>Enumerated list start value not ordinal-1: “3” (ordinal 3)}(hhhjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1j\hjChhhhhMubj])}(hhh]h)}(h:Enumerated list start value not ordinal-1: "5" (ordinal 5)h]h>Enumerated list start value not ordinal-1: “5” (ordinal 5)}(hhhj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjzubah}(h]h ]h"]h$]h&]levelKtypejwsourcehlineKuh1j\hjChhhhhMubetransform_messages] transformerN include_log] decorationNhhub.