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> |
56 | | See <a class="wiki" href="/wiki/linux/OTG">OTG</a> for more info. |
57 | | </p> |
58 | | <h2 id="USBHostMode">USB Host Mode</h2> |
59 | | <p> |
60 | | A 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> |
64 | | A Device mode cable allows connection to a USB host such as a PC. |
65 | | </p> |
66 | | <p> |
| 1 | [[PageOutline]] |
| 2 | |
| 3 | = USB On-The-Go (OTG) = |
| 4 | Certain devices have USB Device Controllers or Dual-Role controllers that can be used in either host mode or device mode. |
| 5 | |
| 6 | This page aims to document how to use and configure USB OTG gadget devices on Linux for boards you wish to connect to a USB Host port and behave like a 'device'. |
| 7 | |
| 8 | See also [wiki:USB_OTG USB_OTG] |
| 9 | |
| 10 | |
| 11 | [=#host] |
| 12 | == USB Host Mode == |
| 13 | A Host mode cable allows connecting to a USB device. No special configuration is necessary for this. |
| 14 | |
| 15 | |
| 16 | [=#device] |
| 17 | == USB Device Mode == |
| 18 | A Device mode cable allows connection to a USB host such as a PC. |
| 19 | |
68 | | </p> |
69 | | <p> |
70 | | There are several Linux gadget drivers in today's linux kernel. These can be found under the <tt>Device Drivers -> USB support -> 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> |
86 | | Additionally 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> |
89 | | Note 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> |
92 | | Note 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> |
99 | | The g_ether gadget driver behaves as a USB-to-Ethernet dongle. Once loaded the device-mode system will add a 'usb<n>' 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> |
| 21 | |
| 22 | There are several Linux gadget drivers in today's linux kernel. These can be found under the {{{Device Drivers -> USB support -> USB Gadget Support menu}}}: |
| 23 | * g_zero (CONFIG_USB_ZERO) |
| 24 | * g_audio (CONFIG_USB_AUDIO) |
| 25 | * [#g_ether g_ether] (CONFIG_USB_ETH) - implement a 'Communication Device Class' (CDC) Ethernet device to create a 'USB to Ethernet' network connection. |
| 26 | * [#g_ncm g_ncm] (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. |
| 27 | * [#g_mass_storage g_mass_storage] (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. |
| 28 | * [#g_serial g_serial] (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. |
| 29 | * g_midi (CONFIG_USB_MIDI_GADGET) - acts as a USB Audio device with one MIDI input and one MIDI output. |
| 30 | * g_printer (CONFIG_USB_G_PRINTER) - channels data between the USB host and a userspace program driving the print engine. |
| 31 | * [#g_cdc g_cdc] (CONFIG_USB_CDC_COMPOSITE) - provides two functions in one configuration: a CDC Ethernet (ECM) link, and a CDC ACM (serial port) link |
| 32 | * 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 |
| 33 | * [#g_multi g_multi] (CONFIG_USB_G_MULTI) - A multifunction composite gadget that can provide Ethernet (RNDIS and/or CDC), mass storage, and ACM serial link interfaces |
| 34 | * [#g_hid g_hid] (CONFIG_USB_G_HID) - A Human Interface Device (HID) gadget that provides a generic interface for things such as keyboards, mice, touchscreens |
| 35 | * [#g_webcam g_webcam] - A Webcam Device |
| 36 | |
| 37 | Additionally The Linux [#configfs 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. See [#configfs below] for more details on how to use this. |
| 38 | |
| 39 | Note 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 ([http://en.wikipedia.org/wiki/Media_Transfer_Protocol Media Transfer Protocol]) device. |
| 40 | |
| 41 | Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configurable (see [https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt here] for details) |
| 42 | |
| 43 | |
| 44 | [=#g_ether] |
| 45 | === g_ether Gadget === |
| 46 | The g_ether gadget driver behaves as a USB-to-Ethernet dongle. Once loaded the device-mode system will add a 'usb<n>' 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. |
| 47 | |
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> |
154 | | The 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> |
160 | | Example (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> |
168 | | Using 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> |
| 88 | * https://www.kernel.org/doc/Documentation/usb/mass-storage.txt |
| 89 | * http://www.linux-usb.org/gadget/file_storage.html |
| 90 | |
| 91 | |
| 92 | [=#g_serial] |
| 93 | === g_serial - Serial Device Gadget === |
| 94 | The 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. |
| 95 | |
| 96 | Example: |
| 97 | * on target device (Gateworks board with OTG controller): |
| 98 | {{{#!bash |
| 99 | modprobe g_serial |
| 100 | }}} |
| 101 | * on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4a7 by default) will appear and behave as a serial device |
| 102 | * module parameters can specify the VID, PID, device version, |
| 103 | manufacturer string, product string, serialnumber |
| 104 | * module parameters can specify whether or not to use CDC ACM, CDC OBEX, and the number of ports to create |
| 105 | |
| 106 | Linux USB Host notes: |
| 107 | * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>' |
| 108 | |
| 109 | Windows USB Host notes: |
| 110 | * see https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt |
| 111 | |
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> |
244 | | Example: |
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> |
253 | | Linux USB Host notes: |
254 | | </p> |
255 | | <ul><li>the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>' |
256 | | </li><li>the cdc_ether driver will enumerate this device as a 'usb<n>' network device |
257 | | </li><li>the usb-storage driver will provide the USB Mass Storage feature |
258 | | </li></ul><p> |
259 | | Windows 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> |
| 141 | * a CDC Ethernet (ECM) link |
| 142 | * a CDC ACM (serial port) link |
| 143 | * a USB Mass Storage device |
| 144 | |
| 145 | Example: |
| 146 | * on target device (Gateworks board with OTG controller): |
| 147 | {{{#!bash |
| 148 | modprobe g_cdc |
| 149 | }}} |
| 150 | * on host device (ie PC) a USB CDC ACM device (VID:PID 1d6b:0104 by default) will appear |
| 151 | * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber |
| 152 | * module parameters can specify the ethernet device and host address and queue length multiplier at high speed |
| 153 | |
| 154 | Linux USB Host notes: |
| 155 | * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>' |
| 156 | * the cdc_ether driver will enumerate this device as a 'usb<n>' network device |
| 157 | * the usb-storage driver will provide the USB Mass Storage feature |
| 158 | |
| 159 | Windows USB Host notes: |
| 160 | * A Multifunction Composite Gadget device will appear in Device Manager |
| 161 | * see [https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt here] for details on Windows configuration |
| 162 | |
291 | | </p> |
292 | | <p> |
293 | | Example: |
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<n> 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> |
302 | | Linux USB Host notes: |
303 | | </p> |
304 | | <ul><li>the uvcvideo driver will enumerate the device and create a /dev/video<n> video capture device |
305 | | </li></ul><p> |
306 | | Windows 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> |
315 | | The 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> |
318 | | Example: |
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<n> 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> |
328 | | Linux USB Host notes: |
329 | | </p> |
330 | | <ul><li>the cdc_ncm driver will enumerate the device and create a /dev/video<n> video capture device |
331 | | </li></ul><p> |
332 | | Windows 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> |
| 185 | |
| 186 | Example: |
| 187 | * on target device (Gateworks board with OTG controller): |
| 188 | {{{#!bash |
| 189 | modprobe g_webcam |
| 190 | }}} |
| 191 | * on host device (ie PC) a 'Linux Foundation Webcam Gadget' device (VID:PID 1d6b:0102 by default) will appear |
| 192 | * on target device (Gateworks board) a /dev/video<n> device will be created and avialable as a Video4Linux output device supporting 320/240 YUYV video |
| 193 | * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber |
| 194 | |
| 195 | Linux USB Host notes: |
| 196 | * the uvcvideo driver will enumerate the device and create a {{{/dev/video<n>}}} video capture device |
| 197 | |
| 198 | Windows USB Host notes: |
| 199 | * A USB Composite device will appear in Device Manager |
| 200 | * A UVC Camera device will appear under Imaging devices in the device manager and be available to capture video |
| 201 | |
| 202 | |
| 203 | [=#g_ncm] |
| 204 | === g_ncm - USB CDC NCM subclass Ethernet Gadget === |
| 205 | The 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. |
| 206 | |
| 207 | Example: |
| 208 | * on target device (Gateworks board with OTG controller): |
| 209 | {{{#!bash |
| 210 | modprobe g_ncm |
| 211 | }}} |
| 212 | * on host device (ie PC) a 'Linux-USB Ethernet Gadget' device (VID:PID 0525:a4a1 by default) will appear |
| 213 | * on target device (Gateworks board) a usb<n> network device will be created |
| 214 | * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber |
| 215 | * module parameters can specify the device and host ethernet addresses and the queue length multiplier used at high speeds |
| 216 | |
| 217 | Linux USB Host notes: |
| 218 | * the cdc_ncm driver will enumerate the device and create a network interface in {{{/sys/class/net}}} |
| 219 | |
| 220 | Windows USB Host notes: |
| 221 | * A NCM Gadget device will appear in Device Manager |
| 222 | * see [http://www.thesycon.de/eng/usb_cdcncm.shtml here] for details about a Windows CDC NCM driver |
| 223 | |
| 224 | |
| 225 | [=#configfs] |
| 226 | === !ConfigFs === |
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> |
| 228 | * usb_f_acm - CDC Serial (ACM - Abstract Control Model) |
| 229 | * usb_f_ecm - CDC Ethernet (ECM - Ethernet Networking Control Model) |
| 230 | * usb_f_eem - CDC Ethernet (EEM - Ethernet Emulation Model) |
| 231 | * usb_f_fs - Filesystem |
| 232 | * usb_f_hid - HID Interface |
| 233 | * usb_f_mass_storage - USB Mass Storage class |
| 234 | * usb_f_midi - MIDI |
| 235 | * usb_f_ncm - CDC Network (NCM - Network Control Model Ethernet) |
| 236 | * usb_f_obex - CDC OBEX (Object Exchange Model) |
| 237 | * usb_f_phonet - CDC Phonet |
| 238 | * usb_f_printer - Printer function |
| 239 | * usb_f_rndis - (Remote Network Driver Interface Specification - Microsoft Ethernet over USB) |
| 240 | * usb_f_serial - Generic serial function |
| 241 | * usb_f_subset - CDC Subset (Ethernet with no control mechanism - just raw data transfer) |
| 242 | * usb_f_uac1 - USB Audio class |
| 243 | * usb_f_uac2 - USB Audio class 2.0 |
| 244 | * usb_f_uvc - USB Video class |
| 245 | |
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 > idVendor |
377 | | <span class="nb">echo </span>0x1234 > idProduct |
378 | | <span class="c"># configure its serial/mfg/product |
379 | | </span>mkdir strings/0x409 |
380 | | <span class="nb">echo </span>myserial > strings/0x409/serialnumber |
381 | | <span class="nb">echo </span>mymfg > strings/0x409/manufacturer |
382 | | <span class="nb">echo </span>myproduct > 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 > 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_<name> 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 > 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 > idVendor |
407 | | <span class="nb">echo </span>0x1234 > idProduct |
408 | | <span class="c"># configure its serial/mfg/product |
409 | | </span>mkdir strings/0x409 |
410 | | <span class="nb">echo </span>myserial > strings/0x409/serialnumber |
411 | | <span class="nb">echo </span>mymfg > strings/0x409/manufacturer |
412 | | <span class="nb">echo </span>myproduct > 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 > 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_<name> 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 > 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 > idVendor |
437 | | <span class="nb">echo </span>0x1234 > idProduct |
438 | | <span class="c"># configure its serial/mfg/product |
439 | | </span>mkdir strings/0x409 |
440 | | <span class="nb">echo </span>myserial > strings/0x409/serialnumber |
441 | | <span class="nb">echo </span>mymfg > strings/0x409/manufacturer |
442 | | <span class="nb">echo </span>myproduct > strings/0x409/product |
443 | | <span class="c"># create configs |
444 | | </span>mkdir configs/c.1 |
| 249 | * Create a CDC ACM Serial device: |
| 250 | {{{#!bash |
| 251 | # mount configfs |
| 252 | mount -t configfs none /sys/kernel/config |
| 253 | # load libcomposite module |
| 254 | modprobe libcomposite |
| 255 | # create a gadget |
| 256 | mkdir /sys/kernel/config/usb_gadget/g1 |
| 257 | # cd to its configfs node |
| 258 | cd /sys/kernel/config/usb_gadget/g1 |
| 259 | # configure it (vid/pid can be anything if USB Class is used for driver compat) |
| 260 | echo 0xabcd > idVendor |
| 261 | echo 0x1234 > idProduct |
| 262 | # configure its serial/mfg/product |
| 263 | mkdir strings/0x409 |
| 264 | echo myserial > strings/0x409/serialnumber |
| 265 | echo mymfg > strings/0x409/manufacturer |
| 266 | echo myproduct > strings/0x409/product |
| 267 | # create a config |
| 268 | mkdir configs/c.1 |
| 269 | # configure it with attributes if needed |
| 270 | echo 120 > configs/c.1/MaxPower |
| 271 | # ensure function is loaded |
| 272 | modprobe usb_f_acm |
| 273 | # create the function (name must match a usb_f_<name> module such as 'acm') |
| 274 | mkdir functions/acm.0 |
| 275 | # associate function with config |
| 276 | ln -s functions/acm.0 configs/c.1 |
| 277 | # enable gadget by binding it to a UDC from /sys/class/udc |
| 278 | echo 0000:01:00.0 > UDC |
| 279 | # to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1 |
| 280 | }}} |
| 281 | * Create a CDC ECM Ethernet device: |
| 282 | {{{#!bash |
| 283 | # mount configfs |
| 284 | mount -t configfs none /sys/kernel/config |
| 285 | # load libcomposite module |
| 286 | modprobe libcomposite |
| 287 | # create a gadget |
| 288 | mkdir /sys/kernel/config/usb_gadget/g1 |
| 289 | # cd to its configfs node |
| 290 | cd /sys/kernel/config/usb_gadget/g1 |
| 291 | # configure it (vid/pid can be anything if USB Class is used for driver compat) |
| 292 | echo 0xabcd > idVendor |
| 293 | echo 0x1234 > idProduct |
| 294 | # configure its serial/mfg/product |
| 295 | mkdir strings/0x409 |
| 296 | echo myserial > strings/0x409/serialnumber |
| 297 | echo mymfg > strings/0x409/manufacturer |
| 298 | echo myproduct > strings/0x409/product |
| 299 | # create a config |
| 300 | mkdir configs/c.1 |
| 301 | # configure it with attributes if needed |
| 302 | echo 120 > configs/c.1/MaxPower |
| 303 | # ensure function is loaded |
| 304 | modprobe usb_f_ecm |
| 305 | # create the function (name must match a usb_f_<name> module such as 'ecm') |
| 306 | mkdir functions/ecm.0 |
| 307 | # associate function with config |
| 308 | ln -s functions/ecm.0 configs/c.1 |
| 309 | # enable gadget by binding it to a UDC from /sys/class/udc |
| 310 | echo 0000:01:00.0 > UDC |
| 311 | # to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1 |
| 312 | }}} |
| 313 | * Create a USB Mass Storage device (with 2 LUN's 16MB each): |
| 314 | {{{#!bash |
| 315 | # mount configfs |
| 316 | mount -t configfs none /sys/kernel/config |
| 317 | # load libcomposite module |
| 318 | modprobe libcomposite |
| 319 | # create a gadget |
| 320 | mkdir /sys/kernel/config/usb_gadget/g1 |
| 321 | # cd to its configfs node |
| 322 | cd /sys/kernel/config/usb_gadget/g1 |
| 323 | # configure it (vid/pid can be anything if USB Class is used for driver compat) |
| 324 | echo 0xabcd > idVendor |
| 325 | echo 0x1234 > idProduct |
| 326 | # configure its serial/mfg/product |
| 327 | mkdir strings/0x409 |
| 328 | echo myserial > strings/0x409/serialnumber |
| 329 | echo mymfg > strings/0x409/manufacturer |
| 330 | echo myproduct > strings/0x409/product |
| 331 | # create configs |
| 332 | mkdir configs/c.1 |