Root/
1 | |
2 | Linux Gadget Serial Driver v2.0 |
3 | 11/20/2004 |
4 | (updated 8-May-2008 for v2.3) |
5 | |
6 | |
7 | License and Disclaimer |
8 | ---------------------- |
9 | This program is free software; you can redistribute it and/or |
10 | modify it under the terms of the GNU General Public License as |
11 | published by the Free Software Foundation; either version 2 of |
12 | the License, or (at your option) any later version. |
13 | |
14 | This program is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
17 | GNU General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU General Public |
20 | License along with this program; if not, write to the Free |
21 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
22 | MA 02111-1307 USA. |
23 | |
24 | This document and the gadget serial driver itself are |
25 | Copyright (C) 2004 by Al Borchers (alborchers@steinerpoint.com). |
26 | |
27 | If you have questions, problems, or suggestions for this driver |
28 | please contact Al Borchers at alborchers@steinerpoint.com. |
29 | |
30 | |
31 | Prerequisites |
32 | ------------- |
33 | Versions of the gadget serial driver are available for the |
34 | 2.4 Linux kernels, but this document assumes you are using |
35 | version 2.3 or later of the gadget serial driver in a 2.6 |
36 | Linux kernel. |
37 | |
38 | This document assumes that you are familiar with Linux and |
39 | Windows and know how to configure and build Linux kernels, run |
40 | standard utilities, use minicom and HyperTerminal, and work with |
41 | USB and serial devices. It also assumes you configure the Linux |
42 | gadget and usb drivers as modules. |
43 | |
44 | With version 2.3 of the driver, major and minor device nodes are |
45 | no longer statically defined. Your Linux based system should mount |
46 | sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the |
47 | /dev nodes matching the sysfs /sys/class/tty files. |
48 | |
49 | |
50 | |
51 | Overview |
52 | -------- |
53 | The gadget serial driver is a Linux USB gadget driver, a USB device |
54 | side driver. It runs on a Linux system that has USB device side |
55 | hardware; for example, a PDA, an embedded Linux system, or a PC |
56 | with a USB development card. |
57 | |
58 | The gadget serial driver talks over USB to either a CDC ACM driver |
59 | or a generic USB serial driver running on a host PC. |
60 | |
61 | Host |
62 | -------------------------------------- |
63 | | Host-Side CDC ACM USB Host | |
64 | | Operating | or | Controller | USB |
65 | | System | Generic USB | Driver |-------- |
66 | | (Linux or | Serial | and | | |
67 | | Windows) Driver USB Stack | | |
68 | -------------------------------------- | |
69 | | |
70 | | |
71 | | |
72 | Gadget | |
73 | -------------------------------------- | |
74 | | Gadget USB Periph. | | |
75 | | Device-Side | Gadget | Controller | | |
76 | | Linux | Serial | Driver |-------- |
77 | | Operating | Driver | and | |
78 | | System USB Stack | |
79 | -------------------------------------- |
80 | |
81 | On the device-side Linux system, the gadget serial driver looks |
82 | like a serial device. |
83 | |
84 | On the host-side system, the gadget serial device looks like a |
85 | CDC ACM compliant class device or a simple vendor specific device |
86 | with bulk in and bulk out endpoints, and it is treated similarly |
87 | to other serial devices. |
88 | |
89 | The host side driver can potentially be any ACM compliant driver |
90 | or any driver that can talk to a device with a simple bulk in/out |
91 | interface. Gadget serial has been tested with the Linux ACM driver, |
92 | the Windows usbser.sys ACM driver, and the Linux USB generic serial |
93 | driver. |
94 | |
95 | With the gadget serial driver and the host side ACM or generic |
96 | serial driver running, you should be able to communicate between |
97 | the host and the gadget side systems as if they were connected by a |
98 | serial cable. |
99 | |
100 | The gadget serial driver only provides simple unreliable data |
101 | communication. It does not yet handle flow control or many other |
102 | features of normal serial devices. |
103 | |
104 | |
105 | Installing the Gadget Serial Driver |
106 | ----------------------------------- |
107 | To use the gadget serial driver you must configure the Linux gadget |
108 | side kernel for "Support for USB Gadgets", for a "USB Peripheral |
109 | Controller" (for example, net2280), and for the "Serial Gadget" |
110 | driver. All this are listed under "USB Gadget Support" when |
111 | configuring the kernel. Then rebuild and install the kernel or |
112 | modules. |
113 | |
114 | Then you must load the gadget serial driver. To load it as an |
115 | ACM device (recommended for interoperability), do this: |
116 | |
117 | modprobe g_serial |
118 | |
119 | To load it as a vendor specific bulk in/out device, do this: |
120 | |
121 | modprobe g_serial use_acm=0 |
122 | |
123 | This will also automatically load the underlying gadget peripheral |
124 | controller driver. This must be done each time you reboot the gadget |
125 | side Linux system. You can add this to the start up scripts, if |
126 | desired. |
127 | |
128 | Your system should use mdev (from busybox) or udev to make the |
129 | device nodes. After this gadget driver has been set up you should |
130 | then see a /dev/ttyGS0 node: |
131 | |
132 | # ls -l /dev/ttyGS0 | cat |
133 | crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 |
134 | # |
135 | |
136 | Note that the major number (253, above) is system-specific. If |
137 | you need to create /dev nodes by hand, the right numbers to use |
138 | will be in the /sys/class/tty/ttyGS0/dev file. |
139 | |
140 | When you link this gadget driver early, perhaps even statically, |
141 | you may want to set up an /etc/inittab entry to run "getty" on it. |
142 | The /dev/ttyGS0 line should work like most any other serial port. |
143 | |
144 | |
145 | If gadget serial is loaded as an ACM device you will want to use |
146 | either the Windows or Linux ACM driver on the host side. If gadget |
147 | serial is loaded as a bulk in/out device, you will want to use the |
148 | Linux generic serial driver on the host side. Follow the appropriate |
149 | instructions below to install the host side driver. |
150 | |
151 | |
152 | Installing the Windows Host ACM Driver |
153 | -------------------------------------- |
154 | To use the Windows ACM driver you must have the files "gserial.inf" |
155 | and "usbser.sys" together in a folder on the Windows machine. |
156 | |
157 | The "gserial.inf" file is given here. |
158 | |
159 | -------------------- CUT HERE -------------------- |
160 | [Version] |
161 | Signature="$Windows NT$" |
162 | Class=Ports |
163 | ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} |
164 | Provider=%LINUX% |
165 | DriverVer=08/17/2004,0.0.2.0 |
166 | ; Copyright (C) 2004 Al Borchers (alborchers@steinerpoint.com) |
167 | |
168 | [Manufacturer] |
169 | %LINUX%=GSerialDeviceList |
170 | |
171 | [GSerialDeviceList] |
172 | %GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7 |
173 | |
174 | [DestinationDirs] |
175 | DefaultDestDir=10,System32\Drivers |
176 | |
177 | [GSerialInstall] |
178 | CopyFiles=GSerialCopyFiles |
179 | AddReg=GSerialAddReg |
180 | |
181 | [GSerialCopyFiles] |
182 | usbser.sys |
183 | |
184 | [GSerialAddReg] |
185 | HKR,,DevLoader,,*ntkern |
186 | HKR,,NTMPDriver,,usbser.sys |
187 | HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" |
188 | |
189 | [GSerialInstall.Services] |
190 | AddService = usbser,0x0002,GSerialService |
191 | |
192 | [GSerialService] |
193 | DisplayName = %GSERIAL_DISPLAY_NAME% |
194 | ServiceType = 1 ; SERVICE_KERNEL_DRIVER |
195 | StartType = 3 ; SERVICE_DEMAND_START |
196 | ErrorControl = 1 ; SERVICE_ERROR_NORMAL |
197 | ServiceBinary = %10%\System32\Drivers\usbser.sys |
198 | LoadOrderGroup = Base |
199 | |
200 | [Strings] |
201 | LINUX = "Linux" |
202 | GSERIAL = "Gadget Serial" |
203 | GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver" |
204 | -------------------- CUT HERE -------------------- |
205 | |
206 | The "usbser.sys" file comes with various versions of Windows. |
207 | For example, it can be found on Windows XP typically in |
208 | |
209 | C:\WINDOWS\Driver Cache\i386\driver.cab |
210 | |
211 | Or it can be found on the Windows 98SE CD in the "win98" folder |
212 | in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will |
213 | need the DOS "expand" program, the Cygwin "cabextract" program, or |
214 | a similar program to unpack these cab files and extract "usbser.sys". |
215 | |
216 | For example, to extract "usbser.sys" into the current directory |
217 | on Windows XP, open a DOS window and run a command like |
218 | |
219 | expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys . |
220 | |
221 | (Thanks to Nishant Kamat for pointing out this DOS command.) |
222 | |
223 | When the gadget serial driver is loaded and the USB device connected |
224 | to the Windows host with a USB cable, Windows should recognize the |
225 | gadget serial device and ask for a driver. Tell Windows to find the |
226 | driver in the folder that contains "gserial.inf" and "usbser.sys". |
227 | |
228 | For example, on Windows XP, when the gadget serial device is first |
229 | plugged in, the "Found New Hardware Wizard" starts up. Select |
230 | "Install from a list or specific location (Advanced)", then on |
231 | the next screen select "Include this location in the search" and |
232 | enter the path or browse to the folder containing "gserial.inf" and |
233 | "usbser.sys". Windows will complain that the Gadget Serial driver |
234 | has not passed Windows Logo testing, but select "Continue anyway" |
235 | and finish the driver installation. |
236 | |
237 | On Windows XP, in the "Device Manager" (under "Control Panel", |
238 | "System", "Hardware") expand the "Ports (COM & LPT)" entry and you |
239 | should see "Gadget Serial" listed as the driver for one of the COM |
240 | ports. |
241 | |
242 | To uninstall the Windows XP driver for "Gadget Serial", right click |
243 | on the "Gadget Serial" entry in the "Device Manager" and select |
244 | "Uninstall". |
245 | |
246 | |
247 | Installing the Linux Host ACM Driver |
248 | ------------------------------------ |
249 | To use the Linux ACM driver you must configure the Linux host side |
250 | kernel for "Support for Host-side USB" and for "USB Modem (CDC ACM) |
251 | support". |
252 | |
253 | Once the gadget serial driver is loaded and the USB device connected |
254 | to the Linux host with a USB cable, the host system should recognize |
255 | the gadget serial device. For example, the command |
256 | |
257 | cat /proc/bus/usb/devices |
258 | |
259 | should show something like this: |
260 | |
261 | T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 |
262 | D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 |
263 | P: Vendor=0525 ProdID=a4a7 Rev= 2.01 |
264 | S: Manufacturer=Linux 2.6.8.1 with net2280 |
265 | S: Product=Gadget Serial |
266 | S: SerialNumber=0 |
267 | C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA |
268 | I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm |
269 | E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms |
270 | I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm |
271 | E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms |
272 | E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms |
273 | |
274 | If the host side Linux system is configured properly, the ACM driver |
275 | should be loaded automatically. The command "lsmod" should show the |
276 | "acm" module is loaded. |
277 | |
278 | |
279 | Installing the Linux Host Generic USB Serial Driver |
280 | --------------------------------------------------- |
281 | To use the Linux generic USB serial driver you must configure the |
282 | Linux host side kernel for "Support for Host-side USB", for "USB |
283 | Serial Converter support", and for the "USB Generic Serial Driver". |
284 | |
285 | Once the gadget serial driver is loaded and the USB device connected |
286 | to the Linux host with a USB cable, the host system should recognize |
287 | the gadget serial device. For example, the command |
288 | |
289 | cat /proc/bus/usb/devices |
290 | |
291 | should show something like this: |
292 | |
293 | T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 |
294 | D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 |
295 | P: Vendor=0525 ProdID=a4a6 Rev= 2.01 |
296 | S: Manufacturer=Linux 2.6.8.1 with net2280 |
297 | S: Product=Gadget Serial |
298 | S: SerialNumber=0 |
299 | C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA |
300 | I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial |
301 | E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms |
302 | E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms |
303 | |
304 | You must explicitly load the usbserial driver with parameters to |
305 | configure it to recognize the gadget serial device, like this: |
306 | |
307 | modprobe usbserial vendor=0x0525 product=0xA4A6 |
308 | |
309 | If everything is working, usbserial will print a message in the |
310 | system log saying something like "Gadget Serial converter now |
311 | attached to ttyUSB0". |
312 | |
313 | |
314 | Testing with Minicom or HyperTerminal |
315 | ------------------------------------- |
316 | Once the gadget serial driver and the host driver are both installed, |
317 | and a USB cable connects the gadget device to the host, you should |
318 | be able to communicate over USB between the gadget and host systems. |
319 | You can use minicom or HyperTerminal to try this out. |
320 | |
321 | On the gadget side run "minicom -s" to configure a new minicom |
322 | session. Under "Serial port setup" set "/dev/ttygserial" as the |
323 | "Serial Device". Set baud rate, data bits, parity, and stop bits, |
324 | to 9600, 8, none, and 1--these settings mostly do not matter. |
325 | Under "Modem and dialing" erase all the modem and dialing strings. |
326 | |
327 | On a Linux host running the ACM driver, configure minicom similarly |
328 | but use "/dev/ttyACM0" as the "Serial Device". (If you have other |
329 | ACM devices connected, change the device name appropriately.) |
330 | |
331 | On a Linux host running the USB generic serial driver, configure |
332 | minicom similarly, but use "/dev/ttyUSB0" as the "Serial Device". |
333 | (If you have other USB serial devices connected, change the device |
334 | name appropriately.) |
335 | |
336 | On a Windows host configure a new HyperTerminal session to use the |
337 | COM port assigned to Gadget Serial. The "Port Settings" will be |
338 | set automatically when HyperTerminal connects to the gadget serial |
339 | device, so you can leave them set to the default values--these |
340 | settings mostly do not matter. |
341 | |
342 | With minicom configured and running on the gadget side and with |
343 | minicom or HyperTerminal configured and running on the host side, |
344 | you should be able to send data back and forth between the gadget |
345 | side and host side systems. Anything you type on the terminal |
346 | window on the gadget side should appear in the terminal window on |
347 | the host side and vice versa. |
348 | |
349 | |
350 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9