Changes between Initial Version and Version 1 of linux/OTG


Ignore:
Timestamp:
10/22/2017 05:28:45 AM (6 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • linux/OTG

    v1 v1  
     1{{{#!html
     2          <div id="wikipage" class="trac-content"><p>
     3</p><div class="wiki-toc">
     4<ol>
     5  <li>
     6    <a href="#USBOn-The-GoOTG">USB On-The-Go (OTG)</a>
     7    <ol>
     8      <li>
     9        <a href="#USBHostMode">USB Host Mode</a>
     10      </li>
     11      <li>
     12        <a href="#USBDeviceModeUDC">USB Device Mode (UDC)</a>
     13        <ol>
     14          <li>
     15            <a href="#g_etherGadget">g_ether Gadget</a>
     16          </li>
     17          <li>
     18            <a href="#g_mass_storage-USBMassStorageDevice">g_mass_storage - USB Mass Storage Device</a>
     19          </li>
     20          <li>
     21            <a href="#g_file_storage-USBMassStorageDevice">g_file_storage - USB Mass Storage Device</a>
     22          </li>
     23          <li>
     24            <a href="#g_serial-SerialDeviceGadget">g_serial - Serial Device Gadget</a>
     25          </li>
     26          <li>
     27            <a href="#g_cdc-CompositeEthernetSerialGadget">g_cdc - Composite Ethernet + Serial Gadget</a>
     28          </li>
     29          <li>
     30            <a href="#g_multi-CompositeEthernetSerialMassStorageGadget">g_multi - Composite Ethernet + Serial + Mass Storage Gadget</a>
     31          </li>
     32          <li>
     33            <a href="#g_hid-HumanInterfaceDeviceHIDGadget">g_hid - Human Interface Device (HID) Gadget</a>
     34          </li>
     35          <li>
     36            <a href="#g_webcam-CompositeUSBAudioandVideoClassGadget">g_webcam - Composite USB Audio and Video Class Gadget</a>
     37          </li>
     38          <li>
     39            <a href="#g_ncm-USBCDCNCMsubclassEthernetGadget">g_ncm - USB CDC NCM subclass Ethernet Gadget</a>
     40          </li>
     41          <li>
     42            <a href="#ConfigFs">ConfigFs</a>
     43          </li>
     44        </ol>
     45      </li>
     46    </ol>
     47  </li>
     48  <li>
     49    <a href="#OpenWrtOTG">OpenWrt OTG</a>
     50  </li>
     51</ol>
     52</div><p>
     53</p>
     54<h1 id="USBOn-The-GoOTG">USB On-The-Go (OTG)</h1>
     55<p>
     56See <a class="wiki" href="/wiki/linux/OTG">OTG</a> for more info.
     57</p>
     58<h2 id="USBHostMode">USB Host Mode</h2>
     59<p>
     60A Host mode cable allows connecting to a USB device.  No special configuration is necessary for this.
     61</p>
     62<h2 id="USBDeviceModeUDC">USB Device Mode (UDC)</h2>
     63<p>
     64A Device mode cable allows connection to a USB host such as a PC. 
     65</p>
     66<p>
     67When used in this mode, the device needs to have a 'Gadget driver' loaded which implements the personality of the device type you want.
     68</p>
     69<p>
     70There are several Linux gadget drivers in today's linux kernel. These can be found under the <tt>Device Drivers -&gt; USB support -&gt; USB Gadget Support</tt> menu:
     71</p>
     72<ul><li>g_zero (CONFIG_USB_ZERO)
     73</li><li>g_audio (CONFIG_USB_AUDIO)
     74</li><li><a class="wiki" href="/wiki/linux/OTG#g_ether">g_ether</a> (CONFIG_USB_ETH) - implement a 'Communication Device Class' (CDC) Ethernet device to create a 'USB to Ethernet' network connection.
     75</li><li><a class="wiki" href="/wiki/linux/OTG#g_ncm">g_ncm</a> (CONFIG_USB_G_NCM) - implement USB CDC NCM subclass standard. NCM is an advanced protocol for Ethernet encapsulation and allows grouping of several ethernet frames into one USB transfer.
     76</li><li><a class="wiki" href="/wiki/linux/OTG#g_mass_storage">g_mass_storage</a> (CONFIG_USB_MASS_STORAGE) - acts as a USB Mass Storage disk driver. Its storage repository can use a regular file or a block device specified as a module parameter or sysfs option.
     77</li><li><a class="wiki" href="/wiki/linux/OTG#g_serial">g_serial</a> (CONFIG_USB_G_SERIAL) - behave as a ACM Serial device to create a 'USB to Serial' connection which can be used to interoperate with MS-Windows hosts or with the Linux-USB 'cdc-acm' driver.
     78</li><li>g_midi (CONFIG_USB_MIDI_GADGET) - acts as a USB Audio device with one MIDI input and one MIDI output.
     79</li><li>g_printer (CONFIG_USB_G_PRINTER) - channels data between the USB host and a userspace program driving the print engine.
     80</li><li><a class="wiki" href="/wiki/linux/OTG#g_cdc">g_cdc</a> (CONFIG_USB_CDC_COMPOSITE) - provides two functions in one configuration:  a CDC Ethernet (ECM) link, and a CDC ACM (serial port) link
     81</li><li>g_acm_ms (CONFIG_USB_G_ACM_MS) - provides two functions in one configuration: a USB Mass Storage device and a CDC ACM (serial port) link
     82</li><li><a class="wiki" href="/wiki/linux/OTG#g_multi">g_multi</a> (CONFIG_USB_G_MULTI) - A multifunction composite gadget that can provide Ethernet (RNDIS and/or CDC), mass storage, and ACM serial link interfaces
     83</li><li><a class="wiki" href="/wiki/linux/OTG#g_hid">g_hid</a> (CONFIG_USB_G_HID) - A Human Interface Device (HID) gadget that provides a generic interface for things such as keyboards, mice, touchscreens
     84</li><li><a class="wiki" href="/wiki/linux/OTG#g_webcam">g_webcam</a> - A Webcam Device
     85</li></ul><p>
     86Additionally The Linux <a class="wiki" href="/wiki/linux/OTG#configfs">Configfs</a> (CONFIG_CONFIGFS_FS) support allows complete dynamic configuration of gadget devices from userspace in which case you can create a single configuration or multi-configuration composite device with one or more of the functions available from drivers/usb/gadget/udc/functions. See <a class="wiki" href="/wiki/linux/OTG#configfs">below</a> for more details on how to use this.
     87</p>
     88<p>
     89Note that only one gadget driver (device personality) can be loaded at a time but there are some 'composite' gadget drivers that behave as 'composite devices' meaning they have multiple endpoints per USB device.  This will seem familiar if you think of how a modern smart-phone works.  Take an Android phone for example:  When plugged into a host PC via micro-USB OTG, it will behave as a storage device (MTP), however if you want to have it behave as a serial debug device you have to go into the developer menu and select this option.  Note that modern smartphones no longer behave as 'USB Mass Storage' devices as this protocol does not allow the device OS to access the filesystem at the same time the host PC does - instead these devices act as an MTP (<a class="ext-link" href="http://en.wikipedia.org/wiki/Media_Transfer_Protocol"><span class="icon">​</span>Media Transfer Protocol</a>) device.
     90</p>
     91<p>
     92Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configuable (see <a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt"><span class="icon">​</span>here</a> for details)
     93</p>
     94<p>
     95<span class="wikianchor" id="g_ether"></span>
     96</p>
     97<h3 id="g_etherGadget">g_ether Gadget</h3>
     98<p>
     99The g_ether gadget driver behaves as a USB-to-Ethernet dongle.  Once loaded the device-mode system will add a 'usb&lt;n&gt;' network device which can be used the same as any other network device.  On the USB host system, a similar network device will appear as long as a driver supporting the 'CDC Ethernet' standard is available.
     100</p>
     101<p>
     102This module can be built with additional support:
     103</p>
     104<ul><li>EEM: CDC Ethernet Emulation Model (EEM) is a newer standard that has a a simpler interface that can be used by more USB host hardware.
     105</li><li>RNDIS: RNDIS support is an additional option (more CPU intensive) that may be more compatible with Windows drivers.
     106</li></ul><p>
     107Example:
     108</p>
     109<ul><li>on target device (Gateworks board with OTG controller):
     110<pre class="wiki">modprobe g_ether
     111</pre><ul><li>usb0 network interface appears on target (treat like any other network interface)
     112</li></ul></li><li>on host device (ie PC) a device with VID:PID 0525:a4a2 will appear conforming to the <a class="ext-link" href="http://en.wikipedia.org/wiki/USB_communications_device_class"><span class="icon">​</span>CDC Ethernet</a> standard
     113<ul><li>usb0 appears on Linux host (using the cdc_ether driver)
     114</li></ul></li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     115</li><li>module parameters can specify the device and host ethernet address and whether or not to use CDC EEM mode
     116</li></ul><p>
     117Linux Host Notes:
     118</p>
     119<ul><li>cdc_ether driver supports this and will create a 'usb&lt;n&gt;' device on the USB host
     120</li></ul><p>
     121Windows Host Notes:
     122</p>
     123<ul><li>the g_ether driver is typically built with RNDIS support enabled which will make it compatible with drivers in Windows7 and above which will appear in the device manager as a 'USB Ethernet/RNDIS Gadget' and can be configured just as any other network interface.
     124</li></ul><p>
     125Reference:
     126</p>
     127<ul><li><a class="ext-link" href="http://en.wikipedia.org/wiki/USB_communications_device_class"><span class="icon">​</span>http://en.wikipedia.org/wiki/USB_communications_device_class</a>
     128</li><li><a class="ext-link" href="http://en.wikipedia.org/wiki/Ethernet_over_USB"><span class="icon">​</span>http://en.wikipedia.org/wiki/Ethernet_over_USB</a>
     129</li></ul><p>
     130<span class="wikianchor" id="g_mass_storage"></span>
     131</p>
     132<h3 id="g_mass_storage-USBMassStorageDevice">g_mass_storage - USB Mass Storage Device</h3>
     133<p>
     134The g_file_storage driver behaves as a USB Mass Storage device such as a USB hard-disk or USB flash drive. You can decide whether to use a 'file' as a backing store, or a block device (ie a flash partition, or a physical disk). The file/device is provided to the module via the 'file' module parameter.
     135</p>
     136<p>
     137If using a backing storage 'file' you must create it beforehand with its desired size. For example to create a 64MB backing store:
     138</p>
     139<pre class="wiki">dd bs=1M count=64 if=/dev/zero of=/backing_file
     140</pre><p>
     141To use this as a backing store:
     142</p>
     143<pre class="wiki">modprobe g_mass_storage file=/backing_file
     144</pre><p>
     145References:
     146</p>
     147<ul><li><a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/mass-storage.txt"><span class="icon">​</span>https://www.kernel.org/doc/Documentation/usb/mass-storage.txt</a>
     148</li><li><a class="ext-link" href="http://www.linux-usb.org/gadget/file_storage.html"><span class="icon">​</span>http://www.linux-usb.org/gadget/file_storage.html</a>
     149</li></ul><p>
     150<span class="wikianchor" id="g_file_storage"></span>
     151</p>
     152<h3 id="g_file_storage-USBMassStorageDevice">g_file_storage - USB Mass Storage Device</h3>
     153<p>
     154The g_file_storage driver behaves as a USB Mass Storage device such as a USB hard-disk or USB flash drive.  You can decide whether to use a 'file' as a backing store, or a block device (ie a flash partition, or a physical disk).  The file/device is provided to the module via the 'file' module parameter.
     155</p>
     156<p>
     157<strong>This gadget driver was repaced with <tt>g_mass_storage</tt> in Linux 3.8</strong>
     158</p>
     159<p>
     160Example (using the first physical disk (/dev/sda) as a backing store):
     161</p>
     162<ul><li>on target device  (Gateworks board with OTG controller):
     163<ul><li>load module specifying block device (ie /dev/sda the first physical disk device)
     164<pre class="wiki">modprobe g_file_storage file=/dev/sda
     165</pre></li></ul></li><li>on host device (ie PC) a USB Mass Storage device (VID:PID 0525:a4a5 by default) will appear and behave as any other USB Mass Storage device (ie flash stick) would.
     166</li><li>module parameters can specify the serialnumber, number of luns to support as well as some other low-level features (see 'modinfo g_file_storage' for details)
     167</li></ul><p>
     168Using a file as a backing store:
     169</p>
     170<ul><li>Create backing storage file (done once, before you load the gadget module)
     171<pre class="wiki">dd bs=1M count=64 if=/dev/zero of=/tmp/backing_file # create empty file
     172</pre><ul><li>you can choose to partition it (ie 'printf "<sub>L</sub>\n" | sfdisk -uS /tmp/backing_file' for a single linux partition) or partition/format it from the host after connection
     173</li><li>make sure you choose a partition/filesystem scheme that is compatible with the USB Host PC you are going to use (ie, Windows doesn't know how to deal with ext2/ext3/ext4 partitions, so you may want to use VFAT or NTFS)
     174</li><li>specify the path to the backing store via the file parameter (ie 'modprobe g_mass_storage file=/tmp/backing_file')
     175</li></ul></li></ul><p>
     176Reference:
     177</p>
     178<ul><li><a class="ext-link" href="http://www.linux-usb.org/gadget/file_storage.html"><span class="icon">​</span>http://www.linux-usb.org/gadget/file_storage.html</a>
     179</li></ul><p>
     180<span class="wikianchor" id="g_serial"></span>
     181</p>
     182<h3 id="g_serial-SerialDeviceGadget">g_serial - Serial Device Gadget</h3>
     183<p>
     184The Serial Gadget supports CDC-ACM and CDC-OBEX which can inter-operate with the MS-Windows hosts or with Linux hosts using the 'cdc-acm' driver to create a 'USB-to-Serial' connection.
     185</p>
     186<p>
     187Example:
     188</p>
     189<ul><li>on target device  (Gateworks board with OTG controller):
     190<ul><li>load module
     191<pre class="wiki">modprobe g_serial
     192</pre></li></ul></li><li>on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4a7 by default) will appear and behave as a serial device
     193</li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     194</li><li>module parameters can specify whether or not to use CDC ACM, CDC OBEX, and the number of ports to create
     195</li></ul><p>
     196Linux USB Host notes:
     197</p>
     198<ul><li>the cdc_acm driver will enumerate this device as '/dev/ttyACM&lt;n&gt;'
     199</li></ul><p>
     200Windows USB Host notes:
     201</p>
     202<ul><li>see <a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt"><span class="icon">​</span>https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt</a>
     203</li></ul><p>
     204Reference:
     205</p>
     206<ul><li><a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt"><span class="icon">​</span>https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt</a>
     207</li></ul><p>
     208<span class="wikianchor" id="g_cdc"></span>
     209</p>
     210<h3 id="g_cdc-CompositeEthernetSerialGadget">g_cdc - Composite Ethernet + Serial Gadget</h3>
     211<p>
     212The g_cdc gadget supports two functions in one configuration:
     213</p>
     214<ul><li>a CDC Ethernet (ECM) link (USB-to-Ethernet connection)
     215</li><li>a CDC ACM (serial port) link (USB-to-Serial connection)
     216</li></ul><p>
     217Example:
     218</p>
     219<ul><li>on target device  (Gateworks board with OTG controller):
     220<ul><li>load module
     221<pre class="wiki">modprobe g_cdc
     222</pre></li></ul></li><li>on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4aa) will appear
     223</li></ul><p>
     224Linux USB Host notes:
     225</p>
     226<ul><li>the cdc_acm driver will enumerate this device as '/dev/ttyACM&lt;n&gt;'
     227</li><li>the cdc_ether driver will enumerate this device as a 'usb&lt;n&gt;' network device
     228</li></ul><p>
     229Windows USB Host notes:
     230</p>
     231<ul><li>A CDC Composite Gadget device will appear in Device Manager
     232</li><li>TODO: Is there a driver available that can use this in Windows?  See g_multi below
     233</li></ul><p>
     234<span class="wikianchor" id="g_multi"></span>
     235</p>
     236<h3 id="g_multi-CompositeEthernetSerialMassStorageGadget">g_multi - Composite Ethernet + Serial + Mass Storage Gadget</h3>
     237<p>
     238The g_multi gadget supports multiple functions in one configuration:
     239</p>
     240<ul><li>a CDC Ethernet (ECM) link
     241</li><li>a CDC ACM (serial port) link
     242</li><li>a USB Mass Storage device
     243</li></ul><p>
     244Example:
     245</p>
     246<ul><li>on target device  (Gateworks board with OTG controller):
     247<ul><li>load module
     248<pre class="wiki">modprobe g_cdc
     249</pre></li></ul></li><li>on host device (ie PC) a USB CDC ACM device (VID:PID 1d6b:0104 by default) will appear
     250</li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     251</li><li>module parameters can specify the ethernet device and host address and queue length multiplier at high speed
     252</li></ul><p>
     253Linux USB Host notes:
     254</p>
     255<ul><li>the cdc_acm driver will enumerate this device as '/dev/ttyACM&lt;n&gt;'
     256</li><li>the cdc_ether driver will enumerate this device as a 'usb&lt;n&gt;' network device
     257</li><li>the usb-storage driver will provide the USB Mass Storage feature
     258</li></ul><p>
     259Windows USB Host notes:
     260</p>
     261<ul><li>A Multifunction Composite Gadget device will appear in Device Manager
     262</li><li>see <a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt"><span class="icon">​</span>here</a> for details on Windows configuration
     263</li></ul><p>
     264References:
     265</p>
     266<ul><li><a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt"><span class="icon">​</span>https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt</a>
     267</li></ul><p>
     268<span class="wikianchor" id="g_hid"></span>
     269</p>
     270<h3 id="g_hid-HumanInterfaceDeviceHIDGadget">g_hid - Human Interface Device (HID) Gadget</h3>
     271<p>
     272The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc
     273</p>
     274<p>
     275Example:
     276</p>
     277<ul><li>on target device  (Gateworks board with OTG controller):
     278<ul><li>load module
     279<pre class="wiki">modprobe g_hid
     280</pre></li></ul></li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     281</li></ul><p>
     282References:
     283</p>
     284<ul><li><a class="ext-link" href="https://www.kernel.org/doc/Documentation/usb/gadget_hid.txt"><span class="icon">​</span>https://www.kernel.org/doc/Documentation/usb/gadget_hid.txt</a>
     285</li></ul><p>
     286<span class="wikianchor" id="g_webcam"></span>
     287</p>
     288<h3 id="g_webcam-CompositeUSBAudioandVideoClassGadget">g_webcam - Composite USB Audio and Video Class Gadget</h3>
     289<p>
     290The g_webcam gadget driver provides a Composite USB Audio and Video Class device.
     291</p>
     292<p>
     293Example:
     294</p>
     295<ul><li>on target device (Gateworks board with OTG controller):
     296<ul><li>load module
     297<pre class="wiki">modprobe g_webcam
     298</pre></li></ul></li><li>on host device (ie PC) a 'Linux Foundation Webcam Gadget' device (VID:PID 1d6b:0102 by default) will appear
     299</li><li>on target device (Gateworks board) a /dev/video&lt;n&gt; device will be created and avialable as a Video4Linux output device supporting 320/240 YUYV video
     300</li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     301</li></ul><p>
     302Linux USB Host notes:
     303</p>
     304<ul><li>the uvcvideo driver will enumerate the device and create a /dev/video&lt;n&gt; video capture device
     305</li></ul><p>
     306Windows USB Host notes:
     307</p>
     308<ul><li>A USB Composite device will appear in Device Manager
     309</li><li>A UVC Camera device will appear under Imaging devices in the device manager and be available to capture video
     310</li></ul><p>
     311<span class="wikianchor" id="g_ncm"></span>
     312</p>
     313<h3 id="g_ncm-USBCDCNCMsubclassEthernetGadget">g_ncm - USB CDC NCM subclass Ethernet Gadget</h3>
     314<p>
     315The g_ncm gadget driver provides a a USB CDC NCM subclass.  NCM is an advanced protocol for Ethernet encapsulation, allowing grouping of several ethernet frames into one USB transfer with various alignment possibilities.
     316</p>
     317<p>
     318Example:
     319</p>
     320<ul><li>on target device (Gateworks board with OTG controller):
     321<ul><li>load module
     322<pre class="wiki">modprobe g_ncm
     323</pre></li></ul></li><li>on host device (ie PC) a 'Linux-USB Ethernet Gadget' device (VID:PID 0525:a4a1 by default) will appear
     324</li><li>on target device (Gateworks board) a usb&lt;n&gt; network device will be created
     325</li><li>module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     326</li><li>module parameters can specify the device and host ethernet addresses and the queue length multiplier used at high speeds
     327</li></ul><p>
     328Linux USB Host notes:
     329</p>
     330<ul><li>the cdc_ncm driver will enumerate the device and create a /dev/video&lt;n&gt; video capture device
     331</li></ul><p>
     332Windows USB Host notes:
     333</p>
     334<ul><li>A NCM Gadget device will appear in Device Manager
     335</li><li>see <a class="ext-link" href="http://www.thesycon.de/eng/usb_cdcncm.shtml"><span class="icon">​</span>here</a> for details about a Windows CDC NCM driver
     336</li></ul><p>
     337<span class="wikianchor" id="configfs"></span>
     338</p>
     339<h3 id="ConfigFs">ConfigFs</h3>
     340<p>
     341The Linux Configfs (CONFIG_CONFIGFS_FS) support allows complete dynamic configuration of gadget devices from userspace in which case you can create a single configuration or multi-configuration composite device with one or more of the functions available from drivers/usb/gadget/udc/functions:
     342</p>
     343<ul><li>usb_f_acm - CDC Serial (ACM - Abstract Control Model)
     344</li><li>usb_f_ecm - CDC Ethernet (ECM - Ethernet Networking Control Model)
     345</li><li>usb_f_eem - CDC Ethernet (EEM - Ethernet Emulation Model)
     346</li><li>usb_f_fs - Filesystem
     347</li><li>usb_f_hid - HID Interface
     348</li><li>usb_f_mass_storage - USB Mass Storage class
     349</li><li>usb_f_midi - MIDI
     350</li><li>usb_f_ncm - CDC Network (NCM - Network Control Model Ethernet)
     351</li><li>usb_f_obex - CDC OBEX (Object Exchange Model)
     352</li><li>usb_f_phonet - CDC Phonet
     353</li><li>usb_f_printer - Printer function
     354</li><li>usb_f_rndis - (Remote Network Driver Interface Specification - Microsoft Ethernet over USB)
     355</li><li>usb_f_serial - Generic serial function
     356</li><li>usb_f_subset - CDC Subset (Ethernet with no control mechanism - just raw data transfer)
     357</li><li>usb_f_uac1 - USB Audio class
     358</li><li>usb_f_uac2 - USB Audio class 2.0
     359</li><li>usb_f_uvc - USB Video class
     360</li></ul><p>
     361Note that not all of the above kernel modules may be available depending on your kernel configuration or BSP.
     362</p>
     363<p>
     364Examples:
     365</p>
     366<ul><li>Create a CDC ACM Serial device:
     367<div class="code"><pre><span class="c"># mount configfs
     368</span>mount -t configfs none /sys/kernel/config
     369<span class="c"># load libcomposite module
     370</span>modprobe libcomposite
     371<span class="c"># create a gadget
     372</span>mkdir /sys/kernel/config/usb_gadget/g1
     373<span class="c"># cd to its configfs node
     374</span><span class="nb">cd</span> /sys/kernel/config/usb_gadget/g1
     375<span class="c"># configure it (vid/pid can be anything if USB Class is used for driver compat)
     376</span><span class="nb">echo </span>0xabcd &gt; idVendor
     377<span class="nb">echo </span>0x1234 &gt; idProduct
     378<span class="c"># configure its serial/mfg/product
     379</span>mkdir strings/0x409
     380<span class="nb">echo </span>myserial &gt; strings/0x409/serialnumber
     381<span class="nb">echo </span>mymfg &gt; strings/0x409/manufacturer
     382<span class="nb">echo </span>myproduct &gt; strings/0x409/product
     383<span class="c"># create a config
     384</span>mkdir configs/c.1
     385<span class="c"># configure it with attributes if needed
     386</span><span class="nb">echo </span>120 &gt; configs/c.1/MaxPower
     387<span class="c"># ensure function is loaded
     388</span>modprobe usb_f_acm
     389<span class="c"># create the function (name must match a usb_f_&lt;name&gt; module such as 'acm')
     390</span>mkdir functions/acm.0
     391<span class="c"># associate function with config
     392</span>ln -s functions/acm.0 configs/c.1
     393<span class="c"># enable gadget by binding it to a UDC from /sys/class/udc
     394</span><span class="nb">echo </span>0000:01:00.0 &gt; UDC
     395<span class="c"># to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1
     396</span></pre></div></li><li>Create a CDC ECM Ethernet device:
     397<div class="code"><pre><span class="c"># mount configfs
     398</span>mount -t configfs none /sys/kernel/config
     399<span class="c"># load libcomposite module
     400</span>modprobe libcomposite
     401<span class="c"># create a gadget
     402</span>mkdir /sys/kernel/config/usb_gadget/g1
     403<span class="c"># cd to its configfs node
     404</span><span class="nb">cd</span> /sys/kernel/config/usb_gadget/g1
     405<span class="c"># configure it (vid/pid can be anything if USB Class is used for driver compat)
     406</span><span class="nb">echo </span>0xabcd &gt; idVendor
     407<span class="nb">echo </span>0x1234 &gt; idProduct
     408<span class="c"># configure its serial/mfg/product
     409</span>mkdir strings/0x409
     410<span class="nb">echo </span>myserial &gt; strings/0x409/serialnumber
     411<span class="nb">echo </span>mymfg &gt; strings/0x409/manufacturer
     412<span class="nb">echo </span>myproduct &gt; strings/0x409/product
     413<span class="c"># create a config
     414</span>mkdir configs/c.1
     415<span class="c"># configure it with attributes if needed
     416</span><span class="nb">echo </span>120 &gt; configs/c.1/MaxPower
     417<span class="c"># ensure function is loaded
     418</span>modprobe usb_f_ecm
     419<span class="c"># create the function (name must match a usb_f_&lt;name&gt; module such as 'ecm')
     420</span>mkdir functions/ecm.0
     421<span class="c"># associate function with config
     422</span>ln -s functions/ecm.0 configs/c.1
     423<span class="c"># enable gadget by binding it to a UDC from /sys/class/udc
     424</span><span class="nb">echo </span>0000:01:00.0 &gt; UDC
     425<span class="c"># to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1
     426</span></pre></div></li><li>Create a USB Mass Storage device (with 2 LUN's 16MB each):
     427<div class="code"><pre><span class="c"># mount configfs
     428</span>mount -t configfs none /sys/kernel/config
     429<span class="c"># load libcomposite module
     430</span>modprobe libcomposite
     431<span class="c"># create a gadget
     432</span>mkdir /sys/kernel/config/usb_gadget/g1
     433<span class="c"># cd to its configfs node
     434</span><span class="nb">cd</span> /sys/kernel/config/usb_gadget/g1
     435<span class="c"># configure it (vid/pid can be anything if USB Class is used for driver compat)
     436</span><span class="nb">echo </span>0xabcd &gt; idVendor
     437<span class="nb">echo </span>0x1234 &gt; idProduct
     438<span class="c"># configure its serial/mfg/product
     439</span>mkdir strings/0x409
     440<span class="nb">echo </span>myserial &gt; strings/0x409/serialnumber
     441<span class="nb">echo </span>mymfg &gt; strings/0x409/manufacturer
     442<span class="nb">echo </span>myproduct &gt; strings/0x409/product
     443<span class="c"># create configs
     444</span>mkdir configs/c.1
     445mkdir configs/c.2
     446mkdir configs/c.3
     447<span class="c"># configure them with attributes if needed
     448</span><span class="nb">echo </span>120 &gt; configs/c.1/MaxPower
     449<span class="nb">echo </span>120 &gt; configs/c.2/MaxPower
     450<span class="nb">echo </span>120 &gt; configs/c.2/MaxPower
     451<span class="c"># ensure function is loaded
     452</span>modprobe usb_f_mass_storage
     453<span class="c"># create the function (name must match a usb_f_&lt;name&gt; module such as 'acm')
     454</span>mkdir functions/mass_storage.0
     455<span class="c"># create backing store(s): in this example 2 LUN's 16MB each
     456</span>dd <span class="nv">bs</span><span class="o">=</span>1M <span class="nv">count</span><span class="o">=</span>16 <span class="k">if</span><span class="o">=</span>/dev/zero <span class="nv">of</span><span class="o">=</span>/tmp/lun0.img <span class="c"># 16MB
     457</span>dd <span class="nv">bs</span><span class="o">=</span>1M <span class="nv">count</span><span class="o">=</span>16 <span class="k">if</span><span class="o">=</span>/dev/zero <span class="nv">of</span><span class="o">=</span>/tmp/lun1.img <span class="c"># 16MB
     458# associate with partitions
     459</span>mkdir functions/mass_storage.0/lun.0
     460<span class="nb">echo</span> /tmp/lun0.img &gt; functions/mass_storage.0/lun.0/file
     461mkdir functions/mass_storage.0/lun.1
     462<span class="nb">echo</span> /tmp/lun1.img &gt; functions/mass_storage.0/lun.1/file
     463<span class="c"># associate function with config
     464</span>ln -s functions/mass_storage.0 configs/c.1
     465<span class="c"># enable gadget by binding it to a UDC from /sys/class/udc
     466</span><span class="nb">echo </span>0000:01:00.0 &gt; UDC
     467<span class="c"># to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1
     468</span></pre></div></li></ul><p>
     469References:
     470</p>
     471<ul><li><a class="ext-link" href="https://lxr.missinglinkelectronics.com/linux/Documentation/usb/gadget_configfs.txt"><span class="icon">​</span>Documentation/usb/gadget_configfs.txt</a>
     472</li><li><a class="ext-link" href="https://wiki.tizen.org/wiki/USB/Linux_USB_Layers/Configfs_Composite_Gadget/General_configuration"><span class="icon">​</span>https://wiki.tizen.org/wiki/USB/Linux_USB_Layers/Configfs_Composite_Gadget/General_configuration</a>
     473</li></ul><h1 id="OpenWrtOTG"><a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> OTG</h1>
     474<p>
     475<a class="wiki" href="/wiki/OpenWrt">OpenWrt</a> packages several of the above Linux kernel modules as packages:
     476</p>
     477<ul><li>g_ether - Kernel modules -&gt; USB Support -&gt; kmod-usb-eth-gadget
     478</li><li>g_mass_storage - Kernel modules -&gt; USB Support -&gt; kmod-usb-mass-storage-gadget
     479</li><li>g_serial - Kernel modules -&gt; USB Support -&gt; kmod-usb-serial-gadget
     480</li></ul><p>
     481You must have gadget support enabled:
     482</p>
     483<ul><li>Kernel modules -&gt; USB Support (kmod-usb-gadget)
     484</li></ul><p>
     485Note that all of these packages will attempt to autoload their respective kernel module so whichever one is alphabetically first will be loaded. You can see what is loaded by looking at the current modules:
     486</p>
     487<div class="code"><pre>lsmod | grep g_*
     488</pre></div
     489}}}