0001 ===============================
0002 Linux Gadget Serial Driver v2.0
0003 ===============================
0004
0005 11/20/2004
0006
0007 (updated 8-May-2008 for v2.3)
0008
0009
0010 License and Disclaimer
0011 ----------------------
0012 This program is free software; you can redistribute it and/or
0013 modify it under the terms of the GNU General Public License as
0014 published by the Free Software Foundation; either version 2 of
0015 the License, or (at your option) any later version.
0016
0017 This program is distributed in the hope that it will be useful,
0018 but WITHOUT ANY WARRANTY; without even the implied warranty of
0019 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0020 GNU General Public License for more details.
0021
0022 You should have received a copy of the GNU General Public
0023 License along with this program; if not, write to the Free
0024 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
0025 MA 02111-1307 USA.
0026
0027 This document and the gadget serial driver itself are
0028 Copyright (C) 2004 by Al Borchers (alborchers@steinerpoint.com).
0029
0030 If you have questions, problems, or suggestions for this driver
0031 please contact Al Borchers at alborchers@steinerpoint.com.
0032
0033
0034 Prerequisites
0035 -------------
0036 Versions of the gadget serial driver are available for the
0037 2.4 Linux kernels, but this document assumes you are using
0038 version 2.3 or later of the gadget serial driver in a 2.6
0039 Linux kernel.
0040
0041 This document assumes that you are familiar with Linux and
0042 Windows and know how to configure and build Linux kernels, run
0043 standard utilities, use minicom and HyperTerminal, and work with
0044 USB and serial devices. It also assumes you configure the Linux
0045 gadget and usb drivers as modules.
0046
0047 With version 2.3 of the driver, major and minor device nodes are
0048 no longer statically defined. Your Linux based system should mount
0049 sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the
0050 /dev nodes matching the sysfs /sys/class/tty files.
0051
0052
0053
0054 Overview
0055 --------
0056 The gadget serial driver is a Linux USB gadget driver, a USB device
0057 side driver. It runs on a Linux system that has USB device side
0058 hardware; for example, a PDA, an embedded Linux system, or a PC
0059 with a USB development card.
0060
0061 The gadget serial driver talks over USB to either a CDC ACM driver
0062 or a generic USB serial driver running on a host PC::
0063
0064 Host
0065 --------------------------------------
0066 | Host-Side CDC ACM USB Host |
0067 | Operating | or | Controller | USB
0068 | System | Generic USB | Driver |--------
0069 | (Linux or | Serial | and | |
0070 | Windows) Driver USB Stack | |
0071 -------------------------------------- |
0072 |
0073 |
0074 |
0075 Gadget |
0076 -------------------------------------- |
0077 | Gadget USB Periph. | |
0078 | Device-Side | Gadget | Controller | |
0079 | Linux | Serial | Driver |--------
0080 | Operating | Driver | and |
0081 | System USB Stack |
0082 --------------------------------------
0083
0084 On the device-side Linux system, the gadget serial driver looks
0085 like a serial device.
0086
0087 On the host-side system, the gadget serial device looks like a
0088 CDC ACM compliant class device or a simple vendor specific device
0089 with bulk in and bulk out endpoints, and it is treated similarly
0090 to other serial devices.
0091
0092 The host side driver can potentially be any ACM compliant driver
0093 or any driver that can talk to a device with a simple bulk in/out
0094 interface. Gadget serial has been tested with the Linux ACM driver,
0095 the Windows usbser.sys ACM driver, and the Linux USB generic serial
0096 driver.
0097
0098 With the gadget serial driver and the host side ACM or generic
0099 serial driver running, you should be able to communicate between
0100 the host and the gadget side systems as if they were connected by a
0101 serial cable.
0102
0103 The gadget serial driver only provides simple unreliable data
0104 communication. It does not yet handle flow control or many other
0105 features of normal serial devices.
0106
0107
0108 Installing the Gadget Serial Driver
0109 -----------------------------------
0110 To use the gadget serial driver you must configure the Linux gadget
0111 side kernel for "Support for USB Gadgets", for a "USB Peripheral
0112 Controller" (for example, net2280), and for the "Serial Gadget"
0113 driver. All this are listed under "USB Gadget Support" when
0114 configuring the kernel. Then rebuild and install the kernel or
0115 modules.
0116
0117 Then you must load the gadget serial driver. To load it as an
0118 ACM device (recommended for interoperability), do this::
0119
0120 modprobe g_serial
0121
0122 To load it as a vendor specific bulk in/out device, do this::
0123
0124 modprobe g_serial use_acm=0
0125
0126 This will also automatically load the underlying gadget peripheral
0127 controller driver. This must be done each time you reboot the gadget
0128 side Linux system. You can add this to the start up scripts, if
0129 desired.
0130
0131 Your system should use mdev (from busybox) or udev to make the
0132 device nodes. After this gadget driver has been set up you should
0133 then see a /dev/ttyGS0 node::
0134
0135 # ls -l /dev/ttyGS0 | cat
0136 crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0
0137 #
0138
0139 Note that the major number (253, above) is system-specific. If
0140 you need to create /dev nodes by hand, the right numbers to use
0141 will be in the /sys/class/tty/ttyGS0/dev file.
0142
0143 When you link this gadget driver early, perhaps even statically,
0144 you may want to set up an /etc/inittab entry to run "getty" on it.
0145 The /dev/ttyGS0 line should work like most any other serial port.
0146
0147
0148 If gadget serial is loaded as an ACM device you will want to use
0149 either the Windows or Linux ACM driver on the host side. If gadget
0150 serial is loaded as a bulk in/out device, you will want to use the
0151 Linux generic serial driver on the host side. Follow the appropriate
0152 instructions below to install the host side driver.
0153
0154
0155 Installing the Windows Host ACM Driver
0156 --------------------------------------
0157 To use the Windows ACM driver you must have the "linux-cdc-acm.inf"
0158 file (provided along this document) which supports all recent versions
0159 of Windows.
0160
0161 When the gadget serial driver is loaded and the USB device connected
0162 to the Windows host with a USB cable, Windows should recognize the
0163 gadget serial device and ask for a driver. Tell Windows to find the
0164 driver in the folder that contains the "linux-cdc-acm.inf" file.
0165
0166 For example, on Windows XP, when the gadget serial device is first
0167 plugged in, the "Found New Hardware Wizard" starts up. Select
0168 "Install from a list or specific location (Advanced)", then on the
0169 next screen select "Include this location in the search" and enter the
0170 path or browse to the folder containing the "linux-cdc-acm.inf" file.
0171 Windows will complain that the Gadget Serial driver has not passed
0172 Windows Logo testing, but select "Continue anyway" and finish the
0173 driver installation.
0174
0175 On Windows XP, in the "Device Manager" (under "Control Panel",
0176 "System", "Hardware") expand the "Ports (COM & LPT)" entry and you
0177 should see "Gadget Serial" listed as the driver for one of the COM
0178 ports.
0179
0180 To uninstall the Windows XP driver for "Gadget Serial", right click
0181 on the "Gadget Serial" entry in the "Device Manager" and select
0182 "Uninstall".
0183
0184
0185 Installing the Linux Host ACM Driver
0186 ------------------------------------
0187 To use the Linux ACM driver you must configure the Linux host side
0188 kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM)
0189 support".
0190
0191 Once the gadget serial driver is loaded and the USB device connected
0192 to the Linux host with a USB cable, the host system should recognize
0193 the gadget serial device. For example, the command::
0194
0195 cat /sys/kernel/debug/usb/devices
0196
0197 should show something like this:::
0198
0199 T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0
0200 D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
0201 P: Vendor=0525 ProdID=a4a7 Rev= 2.01
0202 S: Manufacturer=Linux 2.6.8.1 with net2280
0203 S: Product=Gadget Serial
0204 S: SerialNumber=0
0205 C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA
0206 I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm
0207 E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms
0208 I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm
0209 E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
0210 E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
0211
0212 If the host side Linux system is configured properly, the ACM driver
0213 should be loaded automatically. The command "lsmod" should show the
0214 "acm" module is loaded.
0215
0216
0217 Installing the Linux Host Generic USB Serial Driver
0218 ---------------------------------------------------
0219 To use the Linux generic USB serial driver you must configure the
0220 Linux host side kernel for "Support for Host-side USB", for "USB
0221 Serial Converter support", and for the "USB Generic Serial Driver".
0222
0223 Once the gadget serial driver is loaded and the USB device connected
0224 to the Linux host with a USB cable, the host system should recognize
0225 the gadget serial device. For example, the command::
0226
0227 cat /sys/kernel/debug/usb/devices
0228
0229 should show something like this:::
0230
0231 T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0
0232 D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1
0233 P: Vendor=0525 ProdID=a4a6 Rev= 2.01
0234 S: Manufacturer=Linux 2.6.8.1 with net2280
0235 S: Product=Gadget Serial
0236 S: SerialNumber=0
0237 C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA
0238 I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial
0239 E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
0240 E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms
0241
0242 You must load the usbserial driver and explicitly set its parameters
0243 to configure it to recognize the gadget serial device, like this::
0244
0245 echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id
0246
0247 The legacy way is to use module parameters::
0248
0249 modprobe usbserial vendor=0x0525 product=0xA4A6
0250
0251 If everything is working, usbserial will print a message in the
0252 system log saying something like "Gadget Serial converter now
0253 attached to ttyUSB0".
0254
0255
0256 Testing with Minicom or HyperTerminal
0257 -------------------------------------
0258 Once the gadget serial driver and the host driver are both installed,
0259 and a USB cable connects the gadget device to the host, you should
0260 be able to communicate over USB between the gadget and host systems.
0261 You can use minicom or HyperTerminal to try this out.
0262
0263 On the gadget side run "minicom -s" to configure a new minicom
0264 session. Under "Serial port setup" set "/dev/ttygserial" as the
0265 "Serial Device". Set baud rate, data bits, parity, and stop bits,
0266 to 9600, 8, none, and 1--these settings mostly do not matter.
0267 Under "Modem and dialing" erase all the modem and dialing strings.
0268
0269 On a Linux host running the ACM driver, configure minicom similarly
0270 but use "/dev/ttyACM0" as the "Serial Device". (If you have other
0271 ACM devices connected, change the device name appropriately.)
0272
0273 On a Linux host running the USB generic serial driver, configure
0274 minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device".
0275 (If you have other USB serial devices connected, change the device
0276 name appropriately.)
0277
0278 On a Windows host configure a new HyperTerminal session to use the
0279 COM port assigned to Gadget Serial. The "Port Settings" will be
0280 set automatically when HyperTerminal connects to the gadget serial
0281 device, so you can leave them set to the default values--these
0282 settings mostly do not matter.
0283
0284 With minicom configured and running on the gadget side and with
0285 minicom or HyperTerminal configured and running on the host side,
0286 you should be able to send data back and forth between the gadget
0287 side and host side systems. Anything you type on the terminal
0288 window on the gadget side should appear in the terminal window on
0289 the host side and vice versa.
