\n\t\t\t\tAs seen in the diagram, the USB configFS resides alongside the USB composite driver. The USB composite driver is the standard interface which interacts with the UDC core SW layers. This post won’t go over the details on USB composite, and focus solely on USB configFS, but there are callbacks registered between USB configFS and UDC core that utilize USB composite.<\/p>\n\n\n\n<\/video><\/figure>\n\n\n\nThe basis and backbone behind USB configFS is utilizing the configFS filesystem, in order to define USB gadget parameters using files, directories, and links. The implementation comprises of the following:<\/p>\n\n\n\n
\nConfigFS<\/strong>\n\nFile Directory<\/strong>: fs\/configfs\/dir.c<\/li>\n\n\n\nComments<\/strong>:\n\nFilesystem driver that enables file and link creation for different functionalities, such as USB.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n\nUSB ConfigFS<\/strong>\n\nFile Directory<\/strong>: drivers\/usb\/gadget\/configfs.c<\/li>\n\n\n\nComments<\/strong>:\n\nRegisters USB configFS callbacks to the configFS filesystem. Exposes different configFS files to userspace\/application, in order to configure the USB configuration. This entity interacts closely with USB composite.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\nHow to Initialize USB ConfigFS<\/strong><\/h4>\n\n\n\nSince USB configFS is a filesystem, applications\/users can use file commands to initialize an empty instance.<\/p>\n\n\n\n
# mounts the configFS filesystem \n<\/strong>mount -t configfs none \/sys\/kernel\/config \n\n# initialize USB configFS <\/strong>\nmkdir \/sys\/kernel\/config\/usb_gadget \nmkdir \/sys\/kernel\/config\/usb_gadget\/g1<\/code><\/pre>\n\n\n\nOnce the “g1” directory is created, users will find files and directories already present within it. Technical details and code references for interested folks can be found in the Technical Details section.<\/p>\n\n\n\n
Sample USB ConfigFS Layout:<\/strong><\/p>\n\n\n\nUSB ConfigFS Parameters<\/strong><\/h4>\n\n\n\nThere are several USB configFS parameters throughout the hierarchy, but there are only a few that need to be populated in order to trigger USB enumeration.<\/p>\n\n\n\n
Base Directory<\/u><\/strong> = \/sys\/kernel\/config\/<\/p>\n\n\n\n <\/p>\n\n\n\nDirectory\/File<\/strong><\/th>Software Defined?<\/strong><\/th>Multiple Instances?<\/strong><\/th>Comments<\/strong><\/th><\/tr><\/thead><base>\/usb_gadget<\/strong><\/td>Yes<\/td> No<\/td> Mount-point for USB configFS files and directories.<\/td><\/tr> <base>\/usb_gadget\/<g1><\/strong><\/td>No<\/td> Yes<\/td> Can define multiple USB gadget instances. Each instance will have its own set of files and directories.“g1”<\/strong> can be named differently.<\/td><\/tr><base>\/usb_gadget\/g1\/UDC<\/strong><\/td>Yes<\/td> No<\/td> Carries the UDC device the USB gadget is binded to. The UDC string is defined within the software.<\/td><\/tr> <base>\/usb_gadget\/g1\/idVendor<\/strong><\/td>Yes<\/td> No<\/td> <\/td><\/tr> <base>\/usb_gadget\/g1\/idProduct<\/strong><\/td>Yes<\/td> No<\/td> <\/td><\/tr> <base>\/usb_gadget\/g1\/functions\/*<\/strong><\/td>Yes<\/td> No<\/td> Objects within the “functions” directory define the available USB function drivers available. Examples can be:<\/strong><base>\/usb_gadget\/g1\/configs\/<c.1><\/strong><\/td>No<\/td> Yes<\/td> Defines a set of USB functions that are included in your USB configuration. <base>\/usb_gadget\/g1\/configs\/c.1\/*<\/strong><\/td>No<\/td> No<\/td> Softlinks to USB function driver files under the “functions” <\/strong>folder.<\/td><\/tr><\/tbody><\/table>USB configFS files\/parameters<\/figcaption><\/figure>\n\n\n\nThe above table highlights the bare minimum settings that will need to be added for defining a USB configuration, and binding to the USB UDC.<\/p>\n\n\n\n
Creating a USB Configuration<\/strong><\/h4>\n\n\n\nOnce initializing USB configFS, the following code snippet can be used to initialize a connection with the host. <\/p>\n\n\n\n
It creates a USB device that exposes a USB composition which includes:<\/p>\n\n\n\n
echo 0xa410 > \/sys\/kernel\/config\/usb_gadget\/g1\/idVendor<\/code>echo 0x0001 > \/sys\/kernel\/config\/usb_gadget\/g1\/idProduct<\/code>mkdir \/sys\/kernel\/config\/usb_gadget\/g1\/functions\/mass_storage.0 <\/code>mkdir \/sys\/kernel\/config\/usb_gadget\/g1\/functions\/adb.0<\/code>mkdir \/sys\/kernel\/config\/usb_gadget\/g1\/functions\/rndis.0<\/code>mkdir \/sys\/kernel\/config\/usb_gadget\/g1\/configs\/c.1<\/code>ln -s \/sys\/kernel\/config\/usb_gadget\/g1\/functions\/mass_storage.0 <\/code>\/sys\/kernel\/config\/usb_gadget\/g1\/configs\/c.1\/f1<\/code>ln -s \/sys\/kernel\/config\/usb_gadget\/g1\/functions\/adb.0 <\/code>\/sys\/kernel\/config\/usb_gadget\/g1\/configs\/c.1\/f2<\/code><\/code><\/pre>\n\n\n\n\n
\nUSB VID<\/span>: 0xa410<\/li>\n\n\n\nUSB PID<\/span>: 0x0001<\/li>\n\n\n\nUSB Configuration<\/span> #1\n\nUSB Interface (function) #1 – USB mass storage<\/li>\n\n\n\n USB Interface (function) #2 – USB Android Debug Bridge (ADB)<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\nTrigger USB Enumeration<\/strong><\/h4>\n<\/div>\n\n\n\nAfter setting up the USB configuration, the device can now attempt to enumerate with the host. In terms of USB, the USB device controller (UDC) is the hardware which initiates and handles device mode operations. For the device to be able to connect to a host, the USB software must have a UDC driver enabled.<\/p>\n\n\n\n
Users can check if there is an available UDC by looking at the following directory:<\/p>\n\n\n\n
# check for any available UDCs<\/strong><\/code>ls -l \/sys\/class\/udc<\/code><\/code><\/pre>\n\n\n\nIf there is an available UDC, this will be the string users will echo to the UDC configfs file.<\/p>\n\n\n\n
# USB configFS currently has no associated UDC\n<\/strong>root@raspberrypi0-wifi:\/sys\/kernel\/config\/usb_gadget\/g1# cat UDC\n\n# check for available UDCs \n<\/strong>root@raspberrypi0-wifi:\/sys\/kernel\/config\/usb_gadget\/g1# ls -l \/sys\/class\/udc \n\nlrwxrwxrwx 1 root root 0 Jan 4 07:58 20980000.usb<\/strong> -> ..\/..\/devices\/platform\/soc\/20980000.usb\/udc\/20980000.usb \n\n# trigger USB enumeration on the desired UDC \n<\/strong>root@raspberrypi0-wifi:\/sys\/kernel\/config\/usb_gadget\/g1# echo 20980000.usb > UDC \n\nroot@raspberrypi0-wifi:\/sys\/kernel\/config\/usb_gadget\/g1# cat UDC \n20980000.usb<\/code><\/pre>\n\n\n\nOnce a valid UDC is written, the PC\/host should now have a device appear. In the previous examples, users would see a device that includes mass storage + adb interfaces\/functions.<\/p>\n","protected":false},"excerpt":{"rendered":"
Learn about the basics of USB ConfigFS and how to utilize it to create your own USB composition!<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":["post-1","post","type-post","status-publish","format-standard","hentry","category-technical"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/posts\/1","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1"}],"version-history":[{"count":20,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/posts\/1\/revisions"}],"predecessor-version":[{"id":343,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=\/wp\/v2\/posts\/1\/revisions\/343"}],"wp:attachment":[{"href":"https:\/\/rethinkit.blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=1"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rethinkit.blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=1"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
![\"\"](\"https:\/\/rethinkit.blog\/wp-content\/uploads\/2024\/03\/Flowchart-1-1.png\")