Changes between Version 2 and Version 3 of USB_OTG


Ignore:
Timestamp:
02/01/2018 06:29:12 AM (7 years ago)
Author:
Tim Harvey
Comment:

removed duplicate (old) info that is now on the linux/OTG page

Legend:

Unmodified
Added
Removed
Modified

  • USB_OTG

    v2 v3  
    2525[[Image(https://shop.gateworks.com/image/cache/catalog/GW10086-500x500.png, 150px)]]
    2626
    27 When used in this mode, the device (the Ventana board) needs to have a 'Gadget driver' loaded which impelemnts the personality of the device type you want.  There are several Linux gadget drivers in today's linux kernel:
    28  * g_ether - behave as a 'Communication Device Class' (CDC) Ethernet device to create a 'USB to Ethernet' network connection.
    29  * g_file_storage - acts as a USB Mass Storage disk drive using either a regular file or a block device as its backing store specified as a module parameter or sysfs option
    30  * g_serial - behave as a ACM Serial device to create a 'USB to Serial' connection
    31  * g_cdc - provides two functions in one configuration:  a CDC Ethernet (ECM) link, and a CDC ACM (serial port) link
    32  * g_multi - A multifunction composite gadget that can provide Ethernet (RNDIS and/or CDC), mass storage, and ACM serial link interfaces
    33  * g_hid - A Human Interface Device (HID) gadget that provides a generic interface for things such as keyboards, mice, touchscreens
    34  * g_webcam - A Webcam Device
    35  * g_ncm - USB CDC NCM subclass for Ethernet encapsulation allowing grouping of several ethernet frames into one USB transfer with varying alignment possibilities
     27When used in this mode, the device (the Ventana board) needs to have a 'Gadget driver' loaded which impelemnts the personality of the device type you want.
    3628
    37 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.
    38 
    39 Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configuable (see [https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt here] for details)
    40 
    41 Reference:
    42  * https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt
    43 
    44 
    45 === g_ether Gadget ===
    46 
    47 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.
    48 
    49 This module can be built with additional support:
    50  * 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.
    51  * RNDIS: RNDIS support is an additional option (more CPU intensive) that may be more compatible with Windows drivers.
    52 
    53 Example:
    54  * on target device (Gateworks board with OTG controller):
    55 {{{
    56 modprobe g_ether
    57 }}}
    58   * usb0 network interface appears on target (treat like any other network interface)
    59  * on host device (ie PC) a device with VID:PID 0525:a4a2 will appear conforming to the [http://en.wikipedia.org/wiki/USB_communications_device_class CDC Ethernet] standard
    60   * usb0 appears on Linux host (using the cdc_ether driver)
    61  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    62  * module parameters can specify the device and host ethernet address and whether or not to use CDC EEM mode
    63 
    64 Linux Host Notes:
    65  * cdc_ether driver supports this and will create a 'usb<n>' device on the USB host
    66 
    67 Windows Host Notes:
    68  * 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.
    69 
    70 Reference:
    71  * http://en.wikipedia.org/wiki/USB_communications_device_class
    72  * http://en.wikipedia.org/wiki/Ethernet_over_USB
    73 
    74 
    75 === g_file_storage - USB Mass Storage Device ===
    76 
    77 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.
    78 
    79 Example (using the first physical disk (/dev/sda) as a backing store):
    80  * on target device  (Gateworks board with OTG controller):
    81   * load module specifying block device (ie /dev/sda the first physical disk device)
    82 {{{
    83 modprobe g_file_storage file=/dev/sda
    84 }}}
    85  * 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.
    86  * 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)
    87 
    88 Using a file as a backing store:
    89  * Create backing storage file (done once, before you load the gadget module)
    90 {{{
    91 dd bs=1M count=64 if=/dev/zero of=/tmp/backing_file # create empty file
    92 }}}
    93   * you can choose to partition it (ie 'printf ",,83,,\n" | sfdisk /tmp/backing_file' for a single linux partition) or partition/format it from the host after connection
    94   * 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)
    95   * specify the path to the backing store via the file parameter (ie 'modprobe g_mass_storage file=/tmp/backing_file')
    96 
    97 Reference:
    98  * http://www.linux-usb.org/gadget/file_storage.html
    99 
    100 === g_serial - Serial Device Gadget ===
    101 
    102 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.
    103 
    104 Example:
    105  * on target device  (Gateworks board with OTG controller):
    106   * load module
    107 {{{
    108 modprobe g_serial
    109 }}}
    110  * on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4a7 by default) will appear and behave as a serial device
    111  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    112  * module parameters can specify whether or not to use CDC ACM, CDC OBEX, and the number of ports to create
    113 
    114 Linux USB Host notes:
    115  * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
    116 
    117 Windows USB Host notes:
    118  * see https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt
    119 
    120 
    121 Reference:
    122  * https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt
    123 
    124 
    125 === g_cdc - Composite Ethernet + Serial Gadget ===
    126 
    127 The g_cdc gadget supports two functions in one configuration:
    128  * a CDC Ethernet (ECM) link (USB-to-Ethernet connection)
    129  * a CDC ACM (serial port) link (USB-to-Serial connection)
    130 
    131 Example:
    132  * on target device  (Gateworks board with OTG controller):
    133   * load module
    134 {{{
    135 modprobe g_cdc
    136 }}}
    137  * on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4aa) will appear
    138 
    139 Linux USB Host notes:
    140  * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
    141  * the cdc_ether driver will enumerate this device as a 'usb<n>' network device
    142 
    143 Windows USB Host notes:
    144  * A CDC Composite Gadget device will appear in Device Manager
    145  * TODO: Is there a driver available that can use this in Windows?  See g_multi below
    146 
    147 
    148 === g_multi - Composite Ethernet + Serial + Mass Storage Gadget ===
    149 
    150 The g_multi gadget supports multiple functions in one configuration:
    151  * a CDC Ethernet (ECM) link
    152  * a CDC ACM (serial port) link
    153  * a USB Mass Storage device
    154 
    155 Example:
    156  * on target device  (Gateworks board with OTG controller):
    157   * load module
    158 {{{
    159 modprobe g_cdc
    160 }}}
    161  * on host device (ie PC) a USB CDC ACM device (VID:PID 1d6b:0104 by default) will appear
    162  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    163  * module parameters can specify the ethernet device and host address and queue length multiplier at high speed
    164 
    165 Linux USB Host notes:
    166  * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
    167  * the cdc_ether driver will enumerate this device as a 'usb<n>' network device
    168  * the usb-storage driver will provide the USB Mass Storage feature
    169 
    170 Windows USB Host notes:
    171  * A Multifunction Composite Gadget device will appear in Device Manager
    172  * see [https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt here] for details on Windows configuration
    173 
    174 References:
    175  * https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt
    176 
    177 === g_hid - Human Interface Device (HID) Gadget ===
    178 
    179 The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc
    180 
    181 Example:
    182  * on target device  (Gateworks board with OTG controller):
    183   * load module
    184 {{{
    185 modprobe g_hid
    186 }}}
    187  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    188 
    189 
    190 References:
    191  * https://www.kernel.org/doc/Documentation/usb/gadget_hid.txt
    192 
    193 
    194 === g_webcam - Composite USB Audio and Video Class Gadget ===
    195 
    196 The g_webcam gadget driver provides a Composite USB Audio and Video Class device.
    197 
    198 Example:
    199  * on target device (Gateworks board with OTG controller):
    200   * load module
    201 {{{
    202 modprobe g_webcam
    203 }}}
    204  * on host device (ie PC) a 'Linux Foundation Webcam Gadget' device (VID:PID 1d6b:0102 by default) will appear
    205  * 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
    206  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    207 
    208 Linux USB Host notes:
    209  * the uvcvideo driver will enumerate the device and create a /dev/video<n> video capture device
    210 
    211 Windows USB Host notes:
    212  * A USB Composite device will appear in Device Manager
    213  * A UVC Camera device will appear under Imaging devices in the device manager and be available to capture video
    214 
    215 
    216 === g_ncm - USB CDC NCM subclass Ethernet Gadget ===
    217 
    218 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.
    219 
    220 Example:
    221  * on target device (Gateworks board with OTG controller):
    222   * load module
    223 {{{
    224 modprobe g_ncm
    225 }}}
    226  * on host device (ie PC) a 'Linux-USB Ethernet Gadget' device (VID:PID 0525:a4a1 by default) will appear
    227  * on target device (Gateworks board) a usb<n> network device will be created
    228  * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
    229  * module parameters can specify the device and host ethernet addresses and the queue length multiplier used at high speeds
    230 
    231 Linux USB Host notes:
    232  * the cdc_ncm driver will enumerate the device and create a /dev/video<n> video capture device
    233 
    234 Windows USB Host notes:
    235  * A NCM Gadget device will appear in Device Manager
    236  * see [http://www.thesycon.de/eng/usb_cdcncm.shtml here] for details about a Windows CDC NCM driver
    237 
    238 = OpenWrt OTG =
    239 Use the make kernel_menuconfig to add gadget modules.
    240 
    241 They are located in Device Drivers > USB support > USB Gadget Support
     29For more information on Linux USB Gadget support see [wiki:linux/OTG linux/OTG]